Agent Registration

Agent Registration enables AI agents and LLM-based clients to obtain identity credentials from your AuthKit-powered service. Unlike traditional OAuth flows designed for users in a browser, Agent Registration is purpose-built for programmatic clients that need machine-readable instructions, minimal interaction, and secure credential management.

Agents discover the registration surface through your service’s .well-known/oauth-authorization-server metadata, register with one of several identity types, optionally bind to a user via a claim ceremony, and exchange the resulting identity assertion for an access token or API key.

Agent Registration supports three identity types, selected by the agent based on its context:

Your choice of identity type depends on your application’s data model:

• If entities are owned by users (e.g. a user’s documents, personal settings), enable only service_auth. This ensures every agent is bound to a specific user through the claim ceremony before it can act on their behalf.
• If the resource owner is an organization (e.g. shared team resources, org-wide data), anonymous registrations work well – agents can begin interacting with organization-scoped resources immediately and optionally bind to a user later.

When enabling anonymous, assign it a restricted set of untrusted permissions suitable for exploration only. Sensitive operations should require trusted (post-claim) permissions so that anonymous agents cannot perform them. See Trust levels and scopes for details.

Agents discover your registration endpoints through a standards-based chain defined by RFC 9728:

1. Your API returns a WWW-Authenticate header with a resource_metadata parameter pointing to your Protected Resource Metadata document.
2. The agent fetches /.well-known/oauth-protected-resource and reads the authorization_servers array.
3. The agent fetches the Authorization Server metadata, which includes an agent_auth block with registration endpoints.

# Step 1 — Your API challenges with resource_metadata
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"

# Step 2 — Protected Resource Document points to the AS
curl https://example.com/.well-known/oauth-protected-resource
{
  "resource": "https://example.com",
  "authorization_servers": ["https://authkit_domain"]
}

# Step 3 — AS metadata includes agent_auth
curl https://authkit_domain/.well-known/oauth-authorization-server | jq .agent_auth
{
  "skill": "https://authkit_domain/agent/auth.md",
  "identity_endpoint": "https://authkit_domain/agent/identity",
  "claim_endpoint": "https://authkit_domain/agent/identity/claim",
  "identity_types_supported": ["anonymous", "service_auth"]
}

Set up the link between your protected resource and your authorization server in the WorkOS Dashboard under Authentication → Agents → Configuration → OAuth well-known discovery.

The skill field in the AS metadata points to a generated auth.md document – a step-by-step guide with curl commands tailored to your environment’s configuration. Agents can follow it directly without needing to parse this documentation.

For agents to discover your service, host the auth.md file at the root of your domain (e.g. https://example.com/auth.md). The recommended approach is to reverse-proxy the WorkOS-hosted version so it always reflects your current configuration.

Find the source URL in the WorkOS Dashboard under Authentication → Agents → Configuration → Host auth.md, then configure your server:

async rewrites() {
  return [{
    source: '/auth.md',
    destination: 'https://authkit_domain/agent/auth.md',
  }];
}

{
  "rewrites": [
    { "source": "/auth.md", "destination": "https://authkit_domain/agent/auth.md" }
  ]
}

location = /auth.md {
    proxy_pass https://authkit_domain/agent/auth.md;
    proxy_set_header Host authkit_domain;
    proxy_ssl_server_name on;
}

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/auth.md") {
      return fetch("https://authkit_domain/agent/auth.md");
    }
    return fetch(request);
  }
}

For Cloudflare Enterprise, skip the worker and use a URL rewrite rule instead.

Replace authkit_domain with your environment’s AuthKit domain. The Dashboard provides the exact source URL and configuration snippets for your environment.

Anonymous registration creates an identity with no user binding. The agent receives an identity assertion immediately and can optionally bind to a user later via the claim ceremony.

curl -X POST https://authkit_domain/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "anonymous"}'

The response includes:

• identity.assertion – a signed JWT the agent uses for credential exchange
• claim.token – used to start a claim ceremony later (optional)
• scopes.pre_claim – permissions available before claiming (untrusted)
• scopes.post_claim – permissions available after claiming (trusted)

When the agent knows the user’s email, service_auth registration initiates a mandatory claim ceremony:

curl -X POST https://authkit_domain/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "service_auth", "login_hint": "user@example.com"}'

The response includes a claim.token and claim.attempt.verification_uri – the agent presents this URI to the user to start the claim ceremony.

When an assertion is nearing expiry, the agent rotates it using the refresh token from a previous registration or claim:

curl -X POST https://authkit_domain/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "refresh", "refresh_token": "<refresh_token>"}'

The claim ceremony binds an agent registration to a user, similar to the OAuth 2.0 Device Authorization Flow. It’s required for service_auth and optional for anonymous registrations.

The agent mints a claim attempt using the claim token from registration:

curl -X POST https://authkit_domain/agent/identity/claim \
  -H "Content-Type: application/json" \
  -d '{
    "type": "service_auth",
    "claim_token": "<claim_token>",
    "login_hint": "user@example.com"
  }'

The response includes attempt.verification_uri – a URL for the user.

The agent presents the verification_uri to the user. When they open it:

1. They sign in to AuthKit (if not already authenticated)
2. The page reveals a short user_code
3. The user reads this code back to the agent

The agent submits the code along with its claim token:

curl -X POST https://authkit_domain/agent/identity/claim/complete \
  -H "Content-Type: application/json" \
  -d '{
    "claim_token": "<claim_token>",
    "user_code": "<code from user>"
  }'

On success, the response contains identity.assertion and identity.refresh_token – the agent’s trusted credentials.

After obtaining an identity assertion (from registration or claim completion), the agent exchanges it at the token endpoint for an access token or API key:

curl -X POST https://authkit_domain/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=<identity_assertion>"

The credential type (access token or API key) and its lifetime are configured per environment in the WorkOS Dashboard.

Agent access tokens include the following claims:

The act claim follows the RFC 8693 delegation pattern and is present only after a successful claim ceremony binds a user to the registration.

Once an agent has exchanged its assertion for a credential, your application needs to validate that credential on incoming requests.

Access tokens – For short-lived access tokens, you can validate the JWT locally by verifying the signature and checking expiration. This avoids a network round-trip on every request. If you need to check whether a token has been revoked before expiry, call the validate credential endpoint.

API keys – API keys must be validated server-side. Use the validate credential endpoint to confirm the key is still active and retrieve its associated registration.

To see full details about the agent behind a credential – its identity, organization, claim status, and timestamps – use the get registration endpoint with the registration ID from the access token’s sub claim.

Agent Registration uses two trust levels to control API access:

• Untrusted (pre-claim) – the default for anonymous registrations before a claim ceremony. Grants limited scopes suitable for exploration.
• Trusted (post-claim) – granted after a successful claim ceremony. Grants full scopes.

Configure which scopes map to each trust level in the WorkOS Dashboard under your environment’s agent auth settings.

Configure Agent Registration in the WorkOS Dashboard under Authentication → Agents:

The Registrations tab lists all agent registrations created against your environment, including their current status (unverified, verified, expired, revoked), the associated user, and the organization.

Enable the identity types agents can use to register:

• Service auth – agents register on behalf of a user, confirming identity through a claim ceremony
• Anonymous – agents register instantly with no credentials; users claim ownership when ready

Each method can be independently enabled or disabled.

Credential settings

Set the credential type and lifetime for all agent registrations:

• Credential type – choose whether the token exchange mints an access token (short-lived, re-mintable) or an API key (durable, persisted by the agent)
• Credential expiration – the lifetime of issued credentials

Trust level permissions

Define which permissions are available at each trust level:

• Trusted permissions – granted after a successful claim ceremony. These are the full set of permissions for verified agents.
• Untrusted permissions – granted to anonymous registrations before a claim. Use these for limited, exploratory access.

Only permissions that are enabled for organization API keys appear here. To add a permission to the list, enable it under Authorization > Configuration > Organization API key permissions in the Dashboard.

Discovery

The Discovery section shows:

• Host auth.md – the source URL for your environment’s generated auth.md skill document, with a configuration dialog showing reverse-proxy setup for Nginx, Next.js, Vercel, and Cloudflare (see Hosting auth.md above)
• OAuth well-known discovery – the authorization server metadata URL that agents use to locate your registration endpoints

Once your environment is configured, test the full flow by prompting any AI agent:

Can you follow this guide to set me up with this service? https://example.com/auth.md

The agent will follow the instructions in auth.md to register and exchange its identity assertion for credentials it can use to call your API. The agent will also guide the user through the claim flow if necessary.