> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service accounts

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

```http theme={null}
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)>`.

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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.