Service identities and token handling
Authenticate background services with narrow grants, explicit audiences and a credential lifecycle that operators can manage.
On this page
Before you start
- Service ownership
- Credential storage policy
- Resource audience definitions
A background service calls a resource
The workload authenticates to the issuer, then presents a resource specific grant at the API boundary.
Scroll across the diagram to see all four systems.
Resolve workload identity
Use the configured workload identity or protected client credential.
Request scoped token
Authenticate the client and request the intended resource authority.
Return access grant
Return a bounded token with its granted scope and lifetime.
Call permitted operation
Send the bearer credential in the authorization header over TLS.
Return result or challenge
Validate issuer, audience, expiry and authorization before executing.
Give each workload an accountable identity
Separate a synchronization worker, report exporter and deployment process when their permissions and owners differ. A shared administrator credential makes incident isolation and revocation harder because unrelated operations depend on the same authority.
Prefer supported workload identity or short lived credential mechanisms where the environment provides them. When a secret is necessary, keep it in a protected secret store and deliver it to the workload through an appropriate runtime mechanism. Never ship service credentials in browser code.
Validate the token for this resource
A resource server must validate the token according to the issuer’s supported format and validation mechanism. For a signed token, establish trusted keys and allowed algorithms, then validate issuer, audience and temporal claims. Do not accept an algorithm solely because the untrusted token header names it.
An opaque token may require introspection or another issuer defined mechanism. Clients should not assume that every access token is a JWT or parse a token to infer permissions that the resource server has not granted.
| Validation | Purpose | Failure handling |
|---|---|---|
| Trusted issuer | Reject credentials from an unrelated authority. | Deny authentication. |
| Intended audience | Prevent token substitution across resources. | Deny authentication. |
| Expiry and validity window | Bound the lifetime of the grant. | Obtain a valid grant through the configured flow. |
| Action scope | Limit the permitted operation class. | Deny the action without escalating automatically. |
| Tenant and object policy | Restrict the concrete target. | Apply object authorization independently. |
Keep credentials out of secondary systems
Authorization headers must be redacted in reverse proxy logs, traces, error reporting and support exports. Avoid placing tokens in query strings because URLs are copied into histories, logs and referral contexts. Use TLS for bearer token transport.
Cache an access token only within its intended security context and lifetime. A token cache key may need issuer, audience, client identity, tenant and scope dimensions. Reusing a cached token across those boundaries can create a confused deputy.
GET /api/v1/accounts/account_42 HTTP/1.1
Host: api.example.test
Authorization: Bearer <access_token>
Accept: application/json
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
Cache-Control: no-storeRotate credentials with an overlap and a rollback plan
Define who owns the credential, which workloads use it and how a replacement reaches them. Where the issuer permits overlapping credentials, validate the replacement before revoking the old one. Record revocation as a planned operational change.
Coordinate refresh attempts across concurrent workers. Retry an authentication failure only when the configured flow can produce a valid new credential; repeated refresh after revocation should enter an actionable disconnected state.
Make the authority visible without exposing the secret
Operators need the client identity, issuer, granted scopes, last successful authentication and next renewal action. They do not need to see the token value. Include a credential reference in the runbook so the correct secret can be rotated without searching logs.
Test expired tokens, wrong audience, unknown signing keys, key rotation, revoked grants and a temporarily unavailable issuer. Separate an inability to authenticate from a business operation that was already accepted.
Inspect a service grant
Evaluate token metadata and permission checks independently of any real token value.
/api/v1/accounts/account_42Expected outcome
Resource access permitted
The grant is valid for this resource and permits the read action.
{
"id": "account_42",
"name": "Northstar Operations"
}Content-Type: application/jsonDecision path
- Validate issuer
- Validate intended audience
- Check expiry
- Authorize accounts.read
Input schema 4 fields
| Field | Type | Meaning |
|---|---|---|
issuer_trustedRequired | boolean | Whether validation resolves a trusted issuer. |
audienceRequired | string | Resource audience carried by the grant. |
expires_inRequired | number | Seconds remaining before expiry. |
scopesRequired | array | Action scopes established by token validation. |
Standards and documentation
Explore the protocol specifications and platform guidance for this topic.
Bring the contract into your operating environment.
Discuss an implementation