API authentication (machine clients, SCIM tokens, OIDC clients)

Each integration surface has its own credential. There are no long-lived API keys with administrator powers.

Machine clients (approval requests)

The administrator creates the client under «Manage» › «Third-party requests» and hands over the ID (UUID) and the secret (agcs1_…). The system exchanges them for a five-minute token:

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=intents:write intents:read" \
  https://identity.example.com/v1/machine/token

Answer: {"access_token":"agm1_…","token_type":"Bearer","expires_in":300,"scope":"…"}.

• Only client_secret_basic is accepted.
• RFC 6749 errors: invalid_client (with WWW-Authenticate: Basic realm="authguard-machine"), invalid_request, unsupported_grant_type, invalid_scope.
• Request a new token rather than keeping one past five minutes.
• A machine token never opens a human route, and a browser session never opens a machine route.
• A missing scope gives 403 insufficient_scope.

SCIM tokens

agscim1_ followed by 64 hex digits, sent as Authorization: Bearer. Scopes scim:users and scim:groups. A missing, wrong, expired or revoked token always gets the same 401.

OIDC clients

A confidential service authenticates at the token endpoint with client_secret_basic, client_secret_post or private_key_jwt; a public service uses PKCE without a secret. See Integrate with OIDC.

Good practice

• Keep secrets in a vault, never in code.
• Rotate them periodically and whenever someone with access leaves.
• Never send secrets to support.