Summary

auth.md is WorkOS's emerging agentic-registration profile. It provides a readable onboarding procedure alongside machine-readable 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 have different roles; do not substitute one for another. WorkOS reference overview.

Discovery Shape

Serve the walkthrough as at /auth.md. For an OAuth-protected , publish 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.

{
  "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.

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.

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.

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.

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

Follow the published chain from /auth.md or an API challenge through resource metadata, authorization metadata, registration, any human claim, , 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 , and replay prevention. Test insufficient , rejected account linking, claim expiry, and revocation. Keep secrets out of logs and enforce authorization on every protected operation. Retain the exact reference revision and real-client evidence with the integration.