OAuth Client Credentials Flow Explained

Quick answer

The OAuth client credentials flow lets one machine client get an access token for itself. It is commonly used for service-to-service APIs, backend jobs, workers, internal platforms, and partner integrations where no end user is present.

The client authenticates to the authorization server with its own credential, receives an access token, and calls the resource server with that token.

Use this flow for machine identity, not user login.

When to use client credentials

Use the client credentials flow when the caller is a service, script, worker, backend application, or integration acting as itself.

Examples:

• A billing worker calls an invoice API.
• An internal service calls an account service.
• A scheduled job calls a reporting API.
• A partner backend syncs catalog data.
• A deployment automation service calls an admin API.

Do not use this flow when the API call needs to represent a signed-in human user. For user identity and login, read OAuth 2.0 vs OpenID Connect.

The basic flow

The flow has three main actors:

Actor	Role
Client	The service or application requesting access.
Authorization server	Issues access tokens after authenticating the client.
Resource server	The API that validates the token and serves protected resources.

The simplified flow:

client -> token endpoint -> access token
client -> resource API with bearer token
resource API -> validates token and scopes

The user is not involved.

Token request example

A client requests a token from the authorization server:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=invoices:read invoices:write

The authorization server returns an access token:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:read invoices:write"
}

The client uses the token when calling the API:

GET /invoices
Authorization: Bearer eyJhbGciOi...

What the token represents

A client credentials token represents the client application, not a user.

That distinction matters in logs and authorization checks.

subject = billing-worker
user = none

If an API needs to know which human approved the action, client credentials alone is not enough. The system needs separate audit context, delegation, or a user-based flow.

Client authentication

The client must authenticate to the token endpoint.

Common methods include:

• Client secret.
• Private key JWT.
• Mutual TLS.
• Workload identity or cloud identity in some environments.

Client secrets are common, but they behave like passwords for applications. They must be stored, rotated, and protected carefully.

Read Secret Management Explained before putting client secrets into CI, logs, or local config files.

Scopes in client credentials

A service token should be scoped to the work that service performs.

Good examples:

invoices:read invoices:write
reports:generate
webhooks:publish

Risky examples:

admin:all
*
full_access

The resource server should enforce scopes per endpoint.

Read OAuth Scopes Explained for scope naming and validation.

Token lifetime and caching

Client credentials access tokens should usually be short-lived.

A service can cache the token until it is close to expiration, then request a new one. It should not request a token before every API call if the token is still valid, because that adds load and failure points.

A practical pattern:

cache token -> use until near expiration -> refresh before expiry -> retry token request on transient failure

Do not cache tokens forever. Respect expires_in and handle token endpoint failures clearly.

Resource server validation

The API receiving the token should validate:

• Signature or introspection result.
• Issuer.
• Audience.
• Expiration.
• Client identity.
• Required scopes.
• Tenant or account boundaries.
• Revocation or disablement when applicable.

If the token is valid but lacks permission, return 403 Forbidden. If the token is missing or invalid, return 401 Unauthorized.

Read REST API Status Codes Explained for status code boundaries.

Client credentials vs API keys

Client credentials and API keys both support machine access, but they have different operational properties.

Topic	Client credentials	API key
Token lifetime	Usually short-lived access tokens.	Often long-lived secret.
Issuance	Token endpoint.	Created directly in app or dashboard.
Scope support	Common and expected.	Possible, but custom.
Rotation	Rotate client secret or key material.	Rotate API key secret.
Validation	Token validation or introspection.	Lookup or hash verification.

API keys can be simpler. OAuth client credentials can be stronger when you need token lifetimes, scopes, centralized issuance, and service identity.

Read API Key vs OAuth Token for the larger comparison.

Common mistakes

The first mistake is using client credentials for user login. This flow has no user authentication step.

The second mistake is giving every service the same broad client credential.

The third mistake is storing client secrets in source code, logs, container images, or shared docs.

The fourth mistake is requesting a new token for every API call instead of caching until near expiration.

The fifth mistake is validating only that a token is signed while ignoring audience, issuer, expiration, and scopes.

The sixth mistake is forgetting to disable or rotate credentials when a service is decommissioned.

Practical backend checklist

Before using client credentials:

• Confirm the caller is a machine client, not a user.
• Register one client per service or integration boundary.
• Store client secrets in a secret manager.
• Request only the scopes the service needs.
• Keep access tokens short-lived.
• Cache tokens until near expiration.
• Validate issuer, audience, expiration, and scopes in the API.
• Log client identity without logging secrets or tokens.
• Define rotation and emergency revocation.
• Monitor token failures and unusual usage.

The client credentials flow works best when each service has a clear identity, narrow scopes, and a routine credential lifecycle.

Related reading

Read OAuth 2.0 Explained for Backend Developers for the broader OAuth model, OAuth Scopes Explained for permission labels, and Service Accounts Explained for machine identity ownership. Compare this pattern with API Key vs OAuth Token and API Key Design Best Practices.

For protected API design, read API Authentication Best Practices. For secret handling and monitoring, read Secret Management Explained and Security Event Logging Explained. For the full sequence, browse the Authentication Learning Path, Backend Security Learning Path, and Topics.