Service accounts

A service account is an organization-owned machine identity. It authenticates with the OAuth 2.1 client_credentials grant and receives short-lived access tokens (15 minutes) for calling the platform API — no user, no browser, no interactive login.

Create a service account

Organization admins create service accounts under Settings → Members → Service accounts. Choose a name and the scopes it may request, then copy the client secret — it is shown only once. If you lose it, rotate the secret to get a new one.

Scopes are resource:action — choose read and/or write per resource. Resources: chat, workflows, storage, knowledge, templates, tools, logs — each with :read and :write (e.g. knowledge:read, workflows:write). :write implies :read on the same resource, so a knowledge:write grant also satisfies a knowledge:read requirement.

Get an access token

Send the client id and secret with HTTP Basic auth. Do not send a resource parameter — tokens are opaque and organization-scoped.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X POST "https://<your-host>/api/auth/oauth2/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=knowledge:read tools:write"

The response contains an access_token. Use it as a bearer token against the API:

curl "https://<your-host>/api/v1/service-account/whoami" \
  -H "authorization: Bearer $ACCESS_TOKEN"

{ "organizationId": "...", "clientId": "sa_...", "scopes": ["knowledge:read", "tools:write"] }

A request may only ask for scopes the service account was granted; the token carries the granted scopes and the organization id, and downstream endpoints enforce both.

Rotating, disabling, and deleting

Rotate secret issues a new secret immediately and invalidates the old one — update your consumers before rotating.
Disable stops new tokens from being issued but keeps the account in the list, so you can re-enable it later by recreating. Tokens already issued remain valid until they expire (up to 15 minutes), so disabling is not instantaneous revocation.
Delete permanently removes the service account and its credentials. Any consumer still using its client ID and secret stops working. As with disable, tokens already issued remain valid until they expire (up to 15 minutes). Deletion cannot be undone — to replace a deleted account, create a new one. You can delete an account whether it is active or already disabled.

Workspace access

A service account is created at the organization level, then assigned to a workspace to call that workspace's APIs — the same way a member or team is added to a workspace. An organization or workspace admin opens Settings → Workspace → Members → Add Members or Groups and searches for the service account by name (it appears in the same picker as users and teams), then assigns a role (member or admin).

Access to a workspace endpoint then requires both:

a workspace role — the account must be assigned to the workspace at a role meeting the endpoint (read/write need member; admin actions need admin); and
a capability scope — the token must carry the matching resource:action (e.g. workflows:write).

The token stays organization-scoped. Target a workspace environment per request with ?environmentId=:

curl "https://<your-host>/api/v1/workflows?environmentId=<environment-id>" \
  -H "authorization: Bearer $ACCESS_TOKEN"

An account with the scope but no workspace assignment is rejected with 403.

Notes

A service account has no user. Tokens carry the organization id and the granted scopes only — not a user identity.
The client_credentials grant is reserved for service accounts. Other OAuth clients (for example interactive Mini Apps) cannot use it.