---
title: "auth.md"
description: "Discover agent registration, verify identity, and exchange assertions for scoped access"
url: "https://agentsurface.dev/docs/authentication/auth-md"
lastVerified: 2026-09-24
lastModified: 2026-09-25T05:46:01.000Z
---



## Summary [#summary]

`auth.md` is WorkOS's emerging agentic-registration profile. It provides a readable onboarding procedure alongside machine-readable OAuth discovery. Adopt it when your service supports the registration flow and an intended client can use it. Public documentation does not need to invent a protected resource or registration service.

The current reference separates identity registration from access-token issuance. A provider assertion, a service-issued identity assertion, and an access token have different roles; do not substitute one for another. [WorkOS reference overview](https://github.com/workos/auth.md).

## Discovery Shape [#discovery-shape]

Serve the walkthrough as Markdown at `/auth.md`. For an OAuth-protected API, publish [protected-resource metadata](/docs/authentication/protected-resource-metadata) on the resource server and link to it from the `WWW-Authenticate` challenge - see that page for the 401 response and resource-document shape; `auth.md` adds nothing new there.

What's specific to `auth.md` is the authorization-server side: publish RFC 8414 metadata with the optional registration extension. This example advertises all three methods; remove methods and endpoints the service does not implement.

```json
{
  "issuer": "https://auth.example.com",
  "token_endpoint": "https://auth.example.com/oauth2/token",
  "revocation_endpoint": "https://auth.example.com/oauth2/revoke",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:workos:agent-auth:grant-type:claim"
  ],
  "agent_auth": {
    "skill": "https://example.com/auth.md",
    "identity_endpoint": "https://auth.example.com/agent/identity",
    "claim_endpoint": "https://auth.example.com/agent/identity/claim",
    "events_endpoint": "https://auth.example.com/agent/event/notify",
    "identity_types_supported": ["anonymous", "identity_assertion", "service_auth"],
    "identity_assertion": {
      "assertion_types_supported": ["urn:ietf:params:oauth:token-type:id-jag"]
    },
    "events_supported": ["https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"]
  }
}
```

The ID-JAG URN belongs inside `identity_assertion.assertion_types_supported`, not in `identity_types_supported`. The current endpoint fields are `identity_endpoint`, `claim_endpoint`, and `events_endpoint`. Match your implementation to a pinned profile revision. [Service implementation guide](https://github.com/workos/auth.md/blob/main/agent-services/README.md).

## Flow Selection [#flow-selection]

| Method               | Registration behavior                                                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identity_assertion` | A trusted provider supplies an audience-bound ID-JAG. The service verifies it and may require account-linking confirmation before returning its own identity assertion. |
| `service_auth`       | The agent supplies a login hint. The user signs in to the service and approves a claim ceremony before credentials are issued.                                          |
| `anonymous`          | The service may issue an assertion for restricted pre-claim access; a later claim can bind it to a user.                                                                |

Check accepted assertion types before asking a provider to mint one. In the claim ceremony, the agent presents the verification URL and user code to the person. The person enters the code on the service's authenticated page; they do not send an email OTP back to the agent. [Current agent walkthrough](https://github.com/workos/auth.md/blob/main/AUTH.md).

## Exchange and use [#exchange-and-use]

Exchange the service-issued identity assertion at the advertised token endpoint using the JWT-bearer grant. This is separate from submitting the provider's ID-JAG to registration.

```http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<service-issued-assertion>&resource=https://api.example.com/
```

Use the resulting access token as a bearer credential. A claim ceremony instead polls the token endpoint with `urn:workos:agent-auth:grant-type:claim`, respecting the returned interval and recovery instructions. [JWT-bearer grant](https://www.rfc-editor.org/rfc/rfc7523.html).

## Errors and revocation [#errors-and-revocation]

Document invalid assertions, unavailable methods, account-linking confirmation, stale provider authentication, pending claims, expiry, and throttling. Distinguish revoking one access token from revoking the underlying registration and its derived credentials. The `events_endpoint` receives provider security events; it is not an agent-callable logout route.

## Verification [#verification]

Follow the published chain from `/auth.md` or an API challenge through resource metadata, authorization metadata, registration, any human claim, token exchange, and a permitted request. An OPTIONS response or valid JSON alone does not establish that the flow works.

Verify issuer trust, signature, audience, expiry, authentication freshness, and replay prevention. Test insufficient scopes, rejected account linking, claim expiry, and revocation. Keep secrets out of logs and enforce [authorization](/docs/authentication/oauth-for-agents) on every protected operation. Retain the exact reference revision and real-client evidence with the integration.