# Authentication and token rotation

All API requests carry a bearer token issued by the platform identity service.

## Obtaining a token

POST /v1/auth/token with your client id and secret. Tokens are scoped to one
organisation and expire after 60 minutes.

## Rotating credentials

1. Create a second client secret in the admin console.
2. Deploy the new secret to your integration.
3. Confirm traffic succeeds with the new secret.
4. Revoke the old secret.

Both secrets are valid during the overlap window, so rotation requires no
downtime.

## Handling expiry

A 401 response with code token_expired means the access token has lapsed.
Request a new token and retry once. Do not retry other 4xx responses.

## Storage rules

Never place secrets in browser code or mobile binaries. Server-to-server
integrations should read credentials from environment variables or a managed
secret store.
