workos/auth.md

What it solves

It provides a reference implementation for "agentic registration," a protocol that allows AI agents to authenticate with services on behalf of users. This solves the problem of how an autonomous agent can securely prove its identity and its relationship to a user to gain access to a service's API without requiring the user to manually handle every authentication request.

How it works

The system uses three primary roles: an agent, an agent provider (which issues identity assertions called ID-JAGs), and a service (which accepts these assertions to issue credentials).

Authentication happens through several flows:

1. Identity Assertion (ID-JAG): The agent obtains a signed identity assertion from a provider and presents it to the service to receive an access token.
2. Verified-Email: The agent requests identity via email; the service provides a verification URI and code that the user must complete to link the agent to the user's account.
3. Anonymous Registration: The agent registers anonymously to get limited access, which can later be "claimed" by a user through a verification ceremony to upgrade the agent's permissions.

Who it’s for

• Agent Developers: Who need a template (AUTH.md) and a procedural recipe to implement authentication for their agents.
• Service Providers: Who want to allow AI agents to access their APIs securely using standardized identity assertions.
• Identity Providers (IdPs): Who want to implement the minting of ID-JAGs and handle revocation events for agents.

Highlights

• Reference Implementation: Includes complete sample code for both agent providers and agent services.
• Standardized Protocol: Built on top of RFC 8414, RFC 7009, and RFC 7523, extending them with an agent_auth block for discovery.
• Flexible Auth Flows: Supports high-trust assertions (ID-JAGs), user-verified email flows, and anonymous-to-claimed transitions.
• Skill Manifest: Uses an AUTH.md file to instruct agents on how to authenticate with a specific service.