# Decision Log agent authentication

Decision Log protects its GraphQL, REST facade, and MCP operations with OAuth 2.1 bearer credentials. Agents must request only the access they need, keep credentials out of logs and source control, and preserve the human or machine Actor attached to every audited action.

## Discover

Start with the protected-resource metadata for MCP:

- https://www.decisionlog.ai/.well-known/oauth-protected-resource/api/mcp

Follow its `authorization_servers` entry to the OAuth authorization-server metadata:

- https://www.decisionlog.ai/.well-known/oauth-authorization-server

The authorization-server document is authoritative for the `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `revocation_endpoint`, supported grants, and token authentication methods. A protected request also returns a `WWW-Authenticate: Bearer` challenge whose `resource_metadata` parameter points to the protected-resource document.

Its `agent_auth` block advertises this guide through `skill`, the deployed OAuth dynamic-registration endpoint through `register_uri`, token revocation through `revocation_uri`, and `anonymous` client registration. Here, anonymous means the client can register before it has a Decision Log identity; it does not receive organizational authority. A user must still authenticate and consent through Authorization Code with S256 PKCE before an access token is issued.

## Pick a method

Use Authorization Code with S256 PKCE when a Decision Log user can approve delegated access. Request `decision_log.api` for the API or MCP surface; request `openid profile email` only when identity claims are actually needed.

Use Client Credentials only for a machine client that an authorized organization administrator has provisioned in Decision Log. Do not treat public dynamic registration as authority to act for an organization, and never substitute a human session cookie for an agent credential.

## Register

Authorization Code clients may use the advertised `register_uri` (the OAuth dynamic `registration_endpoint`):

- https://www.decisionlog.ai/api/auth/oauth2/register

Register an HTTPS redirect URI, use `token_endpoint_auth_method: none` for a public PKCE client, and request only supported redirect URIs, grant types, and scopes. Machine clients using `client_credentials` must be provisioned by an authorized Decision Log administrator so the client is bound to an organization, an Actor, permissions, and an audit trail.

Decision Log does not currently accept an `identity_assertion`, an `id-jag` token, or anonymous self-registration as proof of organizational authority.

## Claim

There is no separate `claim_uri` flow. A delegated client is authorized by the user during the Authorization Code consent flow. A machine client is claimed when an authorized administrator provisions it inside the organization. Agents must not infer broader authority from successful client registration.

## Use the credential

For delegated access, send the user to the advertised authorization endpoint with a registered redirect URI, `response_type=code`, requested scope, a cryptographically random `state`, a PKCE `code_challenge`, and `code_challenge_method=S256`. Exchange the returned code at the advertised token endpoint with the original `code_verifier`.

Send the resulting access token on API, REST-facade, or MCP requests:

~~~http
Authorization: Bearer ACCESS_TOKEN
~~~

The canonical programmatic interfaces are https://www.decisionlog.ai/api/graphql, https://www.decisionlog.ai/openapi.json, and https://www.decisionlog.ai/api/mcp, respectively. A token does not bypass workspace scoping, RBAC/ABAC checks, immutable-decision rules, candidate review, or audit requirements.

## Errors

- `invalid_client`: the client identifier or client authentication is invalid, disabled, or revoked.
- `invalid_grant`: the authorization code, refresh token, redirect URI, or PKCE verifier is invalid.
- `invalid_scope`: retry only with a scope listed in authorization-server or protected-resource metadata.
- HTTP 401: read the `WWW-Authenticate` header and follow its `resource_metadata` URL.
- HTTP 403: the authenticated Actor lacks permission; do not retry with broader authority without human approval.

Do not repeatedly retry authentication failures, expose secrets in diagnostics, or probe resources across organization or workspace boundaries.

## Revocation

Revoke a token at the advertised `revocation_uri` (the OAuth `revocation_endpoint`):

- https://www.decisionlog.ai/api/auth/oauth2/revoke

Authenticate the client as required by the authorization-server metadata. Organization administrators should also disable or revoke the underlying machine client when its authority should end. Delete local access tokens, refresh tokens, client secrets, and cached authorization state after revocation.