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.

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: 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.

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).