Skip to main content

​
Service accounts

Service accounts let an organization create credentials for server-side API clients without tying those credentials to a human user. A service account has long-lived client credentials. API clients exchange those credentials for short-lived opaque access tokens, then use the access tokens to call protected CrewAI Platform API endpoints.

​
Create a service account

  1. Open Settings in your organization.
  2. Open Service Accounts.
  3. In the Create service account form, enter a descriptive name, such as Production automation.
  4. Optionally enter a description.
  5. Click Create service account.
  6. Copy the generated Client ID and Client secret from the credentials dialog.
  7. Store the client secret in the secret storage system your organization uses for server-side credentials.
The client secret is shown only once. After you close the credentials dialog, CrewAI cannot show that same secret again.

​
Rotate a client secret

Rotate a service account to generate a new client secret.
  1. Open Settings in your organization.
  2. Open Service Accounts.
  3. Click View details for the service account.
  4. Click Rotate.
  5. Copy the new Client secret from the credentials dialog.
  6. Store the new secret in the secret storage system your organization uses for server-side credentials.
During rotation, the previous secret remains valid until the expiration time shown in the service account details. Use that window to update the systems that depend on the secret. The new client secret is shown only once. If you close the credentials dialog before storing it, rotate again to generate another secret.

​
If you lose the secret

CrewAI stores only a one-way digest of the client secret. The original secret cannot be recovered. If you lose the secret, rotate the service account to generate a new one.

​
Get an access token

Use the OAuth 2.0 client credentials flow to exchange a service account’s client_id and client_secret for an access token. The token endpoint is not versioned: 
POST /oauth/token
Use HTTP Basic authentication with the service account client ID as the username and the client secret as the password. The Authorization header value is Basic <base64(client_id:client_secret)>. 
curl -X POST "https://your-crewai-host.example.com/oauth/token" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
A successful response returns an opaque bearer token: 
{
  "access_token": "sat_...",
  "token_type": "Bearer",
  "expires_in": 3600
}
CrewAI does not issue refresh tokens for service account client credentials. The access token is shown only in the token response. CrewAI stores only a one-way digest of the access token, so the original token cannot be recovered from the database.

​
Call the API with an access token

Send the access token as a bearer token when calling protected Platform API endpoints: 
curl "https://your-crewai-host.example.com/api/v1/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Access tokens are currently scoped to the CrewAI Platform API. They are not JWTs and clients should treat them as opaque strings.

​
Cache access tokens

Access tokens are short-lived. The token response includes expires_in, which tells clients how many seconds the issued token remains valid. CrewAI currently issues service account access tokens with a 3600-second lifetime. Clients should cache and reuse an access token until it is close to expiration. Do not call /oauth/token before every API request. The token endpoint is rate-limited to protect the authentication service and to encourage token reuse. If a client receives a rate-limit response, it should back off and reuse a cached token if one is still valid.

​
Token request errors

/oauth/token returns OAuth 2.0-style errors, not the CrewAI API data / errors envelope. Example: 
{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}
Protected /api/v1/... resource endpoints continue to return CrewAI API error envelopes. Missing, expired, revoked, or invalid bearer tokens return 401 Unauthorized with a WWW-Authenticate: Bearer header.

​
Revoke a service account

Revoke a service account when it should no longer be used.
  1. Open Settings in your organization.
  2. Open Service Accounts.
  3. Click View details for the service account.
  4. Click Revoke.
  5. Optionally enter a reason.
  6. Confirm the revocation.
Revocation disables the service account immediately. Revoked service accounts cannot obtain new access tokens, and existing access tokens for a revoked service account are rejected.