Agent Authentication Documentation Spec

TL;DR

Authentication documentation written for human developers is not enough for AI agents. Agents need a publishable, machine-readable description of the auth surface — supported OAuth grants, scope strings with plain-language descriptions, token endpoints, error codes, and consent UX expectations. Pair narrative docs with .well-known discovery endpoints, OAuth 2.1 dynamic client registration, and structured scope metadata so agents can request the minimum privileges they need and recover from auth failures programmatically.

Definition

Agent authentication documentation is the public specification that describes how an AI agent (autonomous or operator-style) can obtain, refresh, and revoke credentials to call an API on behalf of a user or itself. It combines three layers: (1) human-readable narrative docs, (2) machine-readable discovery and metadata, and (3) reference flows for the grants the API supports.

Unlike traditional API auth docs, agent-targeted documentation assumes the consumer is an automated client with no UI, no clipboard, and limited ability to redirect a user mid-flow.

Why agents need a different auth doc

Human developers tolerate ambiguity. AI agents do not. Three structural differences drive the spec:

• No interactive UI by default. Agents typically run headless, so flows that assume a browser redirect (Authorization Code) need an alternative such as Device Authorization Grant (RFC 8628).
• Machine-readable scope semantics. Agents request least-privilege access; ambiguous scope names like read or admin make this impossible.
• Failure recovery. An agent that hits a 401 must know whether to refresh, re-consent, or escalate to a human, ideally from the error payload alone.

The IETF OAuth 2.1 draft consolidates security best current practice for these scenarios, deprecating the Implicit and Resource Owner Password Credentials grants (draft-ietf-oauth-v2-1). Anthropic's Model Context Protocol authorization spec (2025) similarly pushes toward OAuth 2.1 + dynamic client registration for agent-to-server auth (MCP Authorization).

The seven required sections

A complete agent auth spec contains the following sections, in this order:

1. Identity and protocol summary
2. Discovery endpoints (.well-known)
3. Supported grants and when to use each
4. Scope catalog
5. Token lifecycle
6. Error model
7. Consent and human-in-the-loop UX

1. Identity and protocol summary

State the protocol family, version, and base URLs in a single block at the top.

protocol: OAuth 2.1
base_url: https://api.example.com
auth_server: https://auth.example.com
mcp_compliant: true
supports:
  - authorization_code_pkce
  - device_authorization
  - client_credentials
  - refresh_token

Agents read this block first to decide whether they can integrate at all.

2. Discovery endpoints

Publish OAuth 2.0 Authorization Server Metadata at /.well-known/oauth-authorization-server (RFC 8414) and, if you support OpenID Connect, /.well-known/openid-configuration. Discovery JSON eliminates an entire class of integration bugs because agents do not have to guess endpoint paths.

Minimum required fields:

3. Supported grants and when to use each

For each grant, document the use case, the actor, and the minimum required parameters.

Deprecate and explicitly mark as unsupported: Implicit grant, Resource Owner Password Credentials grant. Both are removed in OAuth 2.1.

4. Scope catalog

Scope strings are an agent's primary least-privilege lever. Document every scope as a structured row:

scopes:
  - name: "calendar.events.read"
    description: "Read calendar events the user owns or is invited to."
    grants:
      - GET /v1/events
      - GET /v1/events/{id}
    requires_consent: true
    sensitive: false
  - name: "calendar.events.write"
    description: "Create, update, and delete calendar events."
    grants:
      - POST /v1/events
      - PATCH /v1/events/{id}
      - DELETE /v1/events/{id}
    requires_consent: true
    sensitive: true

Rules:

• One scope per logical capability. Avoid admin or full_access umbrellas.
• Plain-language description field. Agents surface this string verbatim in consent prompts.
• Mark sensitive: true for scopes touching PII, financial data, or destructive operations.
• List the exact endpoints each scope grants. This is the contract.

5. Token lifecycle

Specify TTLs, refresh behavior, rotation policy, and revocation.

6. Error model

Error responses are the agent's recovery contract. Document every error with its meaning and the recommended agent action.

Return errors in JSON, include WWW-Authenticate headers per RFC 6750, and provide a stable error_code string distinct from human-facing error_description.

7. Consent and human-in-the-loop UX

Document what your consent screen shows, since agents must explain it to the user. At minimum:

• The integrating client name and verified status.
• The exact list of scopes requested, with the description strings rendered verbatim.
• The data residency and retention summary.
• A clear revoke path with the URL.

For device flow, document the verification URI, expected user code length, polling interval, and expiry.

Example: full minimal spec block

auth:
  protocol: OAuth 2.1
  discovery: https://auth.example.com/.well-known/oauth-authorization-server
  grants:
    - authorization_code
    - device_code
    - client_credentials
    - refresh_token
  pkce: required
  device_flow:
    verification_uri: https://example.com/device
    polling_interval_s: 5
    code_lifetime_s: 600
  token:
    access_ttl_s: 3600
    refresh_ttl_s: 2592000
    refresh_rotation: true
  errors:
    format: rfc6749
    www_authenticate: true
  registration:
    dynamic: true
    endpoint: https://auth.example.com/register

Common mistakes

1. Documenting only Authorization Code flow. Most autonomous agents cannot complete a browser redirect.
2. Using umbrella scopes (read, write, admin). Blocks least-privilege requests.
3. Returning HTML error pages on 401. Agents cannot parse these reliably.
4. Omitting the .well-known endpoint. Forces every agent to hard-code paths.
5. Skipping refresh token rotation. Long-lived RTs without rotation are the highest-impact agent token-theft risk.
6. No revocation endpoint. Users have no kill switch when an agent misbehaves.
7. Treating client_credentials and user-delegated flows interchangeably. They have different scope and audit semantics.

How to apply: documentation checklist

• [ ] Publish /.well-known/oauth-authorization-server with full RFC 8414 metadata
• [ ] List every supported grant with use case and required params
• [ ] Mark unsupported grants explicitly (Implicit, ROPC)
• [ ] Provide a structured scope catalog with descriptions, endpoints, and sensitive flags
• [ ] Document access and refresh token TTLs, rotation policy, and reuse detection
• [ ] Provide a complete error table mapping HTTP + error to agent action
• [ ] Describe consent UX: client name, scopes shown, revoke URL
• [ ] Support OAuth 2.1 PKCE with S256 for all interactive flows
• [ ] Offer dynamic client registration (RFC 7591) where feasible
• [ ] Mirror the spec in an MCP-compatible authorization document if you publish an MCP server

FAQ

Q: Do I need OpenID Connect on top of OAuth 2.1?

Only if agents need user identity claims (email, sub) in addition to access tokens. For pure API authorization, OAuth 2.1 alone is sufficient. If you do add OIDC, publish /.well-known/openid-configuration alongside the OAuth metadata.

Q: Should I support API keys for agents?

API keys are acceptable for non-user-delegated, server-to-server agent traffic. They should never substitute for OAuth flows that require user consent. If you offer keys, document scoping, rotation, and revocation with the same rigor as OAuth.

Q: Is the Device Authorization Grant secure enough for agents?

Yes, when implemented per RFC 8628 with rate-limited polling, short-lived device codes, and a verification URI shown to the user out of band. It is the recommended grant for headless agents that need user consent.

Q: How does this relate to the Model Context Protocol (MCP)?

MCP servers are expected to authorize agents per the MCP authorization spec, which is itself an OAuth 2.1 profile. If you operate an MCP server, your agent auth documentation is effectively the MCP authorization document; align scope strings and error semantics accordingly.

Q: What about long-running agents that exceed the access token TTL?

Document refresh token semantics explicitly: TTL, rotation, reuse detection, and the action an agent should take when a refresh fails. Long-running agents should refresh proactively (e.g., when 80% of access TTL has elapsed) rather than reactively on 401.

Q: Can the same documentation serve human developers?

Yes — the structured layer (discovery JSON, scope catalog YAML, error tables) is also the most useful reference for human developers. The narrative sections that explain when to use each grant are what humans typically need beyond the structured spec.