Machine-to-machine API access

When one of your systems needs to call the Freeday API on its own — without a person signing in — it authenticates as an API client. An API client is a client ID and secret that your system exchanges for a short-lived access token, then presents that token as a bearer credential on API calls. Each client is granted only the scopes you choose, so it can do exactly what you intend and nothing more.

Use this for server-to-server automation. For example, you can grant a client the scope to rotate an integration connector's API key, and have your own system rotate that key on a schedule.

1. Create an API client

In the Freeday portal, go to Settings → API clients and create a client. Give it a name and grant the scopes it needs. Only admins of your company can see this page and manage API clients.

When the client is created, its secret is shown once. Copy it and store it somewhere safe — Freeday never shows or returns it again. If you lose it, delete the client and create a new one.

You now have two values: a client ID and a client secret.

2. Get an access token

Exchange the client ID and secret for an access token using the OAuth 2.0 client-credentials grant. Send the client ID and secret as HTTP Basic auth, and the scope you want in the form body:

curl -X POST https://api.freeday.ai/platform/v1/auth/token/client-credentials \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=connector:write

The response contains an access token valid for one hour. There is no refresh token — request a new token when the old one is close to expiring.

{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Here expires_in is the token's lifetime in seconds, returned as a JSON number.

See Client credentials in the API reference for the full endpoint contract.

3. Call the API

Send the token as a bearer credential on each request:

curl https://api.freeday.ai/… \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A request only succeeds if the token carries a scope that covers it. Because tokens are short-lived, fetch a new one before the current token expires so an automated job never stalls on an expired token.

Example: chat with a digital employee from your server

Grant the conversations:create and realtime:access scopes, then follow Server-to-server (API client) in the realtime guide.

Example: rotate an integration's API key

Some integrations authenticate to your systems with an API key that Freeday stores on a connector. If your security policy rotates that key periodically, an API client can update the stored key automatically instead of someone doing it by hand.

1. Grant the scope. Create (or reuse) an API client that has the connector:write scope.
2. Find the connector. In the portal, go to Settings → Connectors to see your integration connectors and their IDs. Note the ID of the connector whose key you want to rotate.
3. Get a token with the connector:write scope (step 2 above).
4. Send the new key. Update the connector with the new API key:

curl -X PUT https://api.freeday.ai/integrations/v1/connectors/api-keys/CONNECTOR_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "NEW_API_KEY"}'

The new key takes effect immediately and the previous key is no longer used. The stored key is write-only: Freeday never returns it, so a successful response confirms the rotation without echoing the secret back.

See Connectors in the API reference for the list and rotate endpoints, and Auth for the token endpoint.

Example: act for the companies you manage

If your company manages other companies in Freeday, one API client can work for all of them.

1. Grant the scope. Give the API client the companies:impersonate scope, plus the scopes it needs in those companies.
2. Name the company. Add company_id when you request the token:

curl -X POST https://api.freeday.ai/platform/v1/auth/token/client-credentials \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=conversations:create \
  -d company_id=MANAGED_COMPANY_ID

The token works only in that company. Request one token for each company. Without companies:impersonate, or for a company yours does not manage, the request fails with unauthorized_client.

Managing clients

• Rotate a client secret by creating a new API client, moving your systems over to it, and then deleting the old one.
• Revoke access by deleting the client in Settings → API clients. It can no longer obtain new tokens, and any token it already holds stops working once it expires (within the hour).