auth.md Registration Flows

Pre-registration is the highest-priority auth.md flow. The service has already issued credentials out-of-band (via email, admin panel, or enterprise agreement). The agent uses pre-issued credentials without any in-band registration step.

Pre-registration is used when credentials were distributed before the first API call. No HTTP registration request is sent. The agent uses the pre-issued API key or access token directly.

This is the simplest flow operationally. It is commonly used in B2B integrations where the service relationship is established before agent deployment.

# /auth.md – pre-registration example

## Registration

register_uri: https://api.example.com/agent/register
identity_types_supported: [service]
credential_types_supported: [api_key]

## Flows

Pre-registration is the preferred flow. Contact [email protected] for an API key.
Pre-registered agents: Authorization: ApiKey <key>

CIMD (Client Identity Metadata Document) is the auth.md flow where the agent presents a signed ID-JAG identity assertion from a trusted identity provider. The service validates the assertion and issues credentials automatically without human approval.

CIMD enables trust-based automatic agent registration. An agent's identity is vouched for by a trusted identity provider. The agent presents a signed JWT assertion (ID-JAG) to the service's register_uri. The service validates the assertion's signature and, if trusted, issues credentials automatically.

The identity assertion carries: the agent's identity (sub), the issuing provider (iss), the target service audience (aud), and requested scopes. The service fetches the provider's JWKS to verify the signature.

// Agent POSTs to register_uri with ID-JAG
POST /agent/register HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <signed-id-jag>

HTTP/1.1 201 Created
{"api_key": "sk_live_abc123", "scopes": ["read:data"]}

DCR (Dynamic Client Registration, RFC 7591) is the auth.md flow where the agent registers as an OAuth 2.0 client by POSTing metadata to the registration endpoint. The service responds with client_id and client_secret for use with the client_credentials grant.

Dynamic Client Registration (RFC 7591) lets agents register programmatically without pre-existing trust. The agent POSTs its metadata and receives OAuth credentials.

After registration the agent uses the standard client_credentials grant: POST to the token endpoint with client_id and client_secret to get an access token, then use it as a Bearer token.

The auth.md file should include the token_endpoint so agents can complete the full flow without additional discovery.

// Step 1: Register
POST /agent/register HTTP/1.1
Content-Type: application/json
{"client_name":"my-agent","grant_types":["client_credentials"],"scope":"read:data"}

// Response
{"client_id":"agent_abc","client_secret":"secret_xyz","token_endpoint":"https://api.example.com/oauth/token"}

// Step 2: Get token
POST /oauth/token
grant_type=client_credentials&client_id=agent_abc&client_secret=secret_xyz

The anonymous flow allows agents to access a service without any registration or credentials. No Authorization header is required. Services declaring anonymous access typically apply IP-based rate limiting. This is the fallback flow when no other flow is applicable.

Anonymous access is declared when the service is accessible without credentials. The agent reads the anonymous flow in auth.md and calls the API without any Authorization header.

Typically rate-limited by IP. Appropriate for: public data APIs, free tier access, read-only endpoints, or preview access.

For agents, anonymous means no registration, no token management, and no credential rotation.

// Agent call without credentials
GET /api/public-data HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87