Every developer building with AI agents has encountered the same tedious bottleneck this month. To give an agent access to a third-party service, a human must first log into a dashboard, navigate to an API settings page, generate a secret key, and manually paste that string into an environment variable or a configuration file. This human-in-the-loop requirement creates a hard ceiling for autonomy. We are building agents capable of writing complex code and managing tickets, yet we still force them to wait for a human to copy and paste a password. This friction is not just a nuisance; it is a fundamental architectural mismatch between how humans access the web and how autonomous agents operate.
The Mechanics of Programmatic Discovery
WorkOS is attempting to solve this by introducing auth.md, an open protocol designed to let AI agents register themselves and acquire permissions without human intervention. The core of this system is a standardized discovery path. Instead of relying on a developer to read a PDF or a documentation site, an agent simply looks for a markdown file at `https://service.com/auth.md`. This file serves as a dual-purpose artifact: it provides a human-readable guide for developers and a machine-readable entry point for agents to understand the service's authentication requirements, available scopes, and the procedures for issuing or revoking credentials.
To move from a descriptive markdown file to a functional connection, the protocol utilizes a two-step discovery hop through well-known paths. First, the agent accesses `/.well-known/oauth-protected-resource` to find the Protected Resource Metadata (PRM), which identifies the resource and points the agent toward the correct authorization server. The agent then moves to `/.well-known/oauth-authorization-server` to locate the `agent_auth` block. This block contains the critical technical endpoints required for automation: the `register_uri` for initial registration, the `claim_uri` for asserting identity, the `revocation_uri` for killing access, and the `identity_types_supported` value which defines what forms of identity the server accepts.
This discovery process is designed to be resilient even when an agent arrives at an API with zero prior knowledge. If an agent attempts to access a protected endpoint and receives a 401 Unauthorized response, the service can provide a bootstrap point directly in the response header using `WWW-Authenticate: Bearer resource_metadata="..."`. This allows the agent to trigger the discovery process in real-time. By standardizing these paths, WorkOS ensures that if a service provider changes their authentication endpoints or updates their policy, the agent can adapt dynamically at runtime without requiring a developer to push a new code deployment or update a config file.
From Static API Keys to Dynamic Identity Grants
The shift from traditional API keys to the auth.md protocol represents a fundamental change in how trust is established between a service and an agent. For years, the industry has relied on unscoped API keys or long-lived session tokens. These are essentially static passwords that, once leaked, grant total access to the account. Because these keys lack granular scope and are often shared across multiple sessions, auditing becomes a nightmare and revoking access to a single compromised agent usually requires rotating the key for every other single integration, causing widespread downtime.
auth.md replaces this static model with two distinct authentication flows: the Agent Verified flow and the User Claimed flow. In the Agent Verified flow, a trusted platform like OpenAI or Anthropic acts as the identity provider. The agent obtains an Identity-JSON Agent Grant (ID-JAG) specifically for a target audience and sends a POST request to the service's `/agent/auth` endpoint. The server then extracts the `kid` (Key ID) and `alg` (Algorithm) from the ID-JAG header to retrieve the provider's JSON Web Key Set (JWKS) and verify the signature. The server performs a rigorous check of claims including `aud` (audience), `exp` (expiration), `iat` (issued at), `jti` (JWT ID), and `client_id`. This allows for synchronous, automated registration where the identity is cryptographically guaranteed by the platform provider, removing the need for any human interaction.
When a trusted provider is not available, the User Claimed flow allows a user to bind an agent to their account using a One-Time Password (OTP). The agent requests an OTP via `/agent/auth/claim`, the user receives the code via email, and the agent submits it to `/agent/auth/claim/complete`. This flow offers two security postures. The anonymous start allows an agent to receive limited, pre-defined permissions immediately, which are then upgraded once the OTP is verified. In this scenario, the API key remains the same while the permissions are elevated in place. Conversely, the email-first approach requires the email to be submitted and verified before any credentials are issued, catering to high-security environments where pre-authentication access is forbidden.
This architecture introduces a critical security constraint: the strict prohibition of refresh tokens for ID-JAG verified access. In standard OAuth flows, refresh tokens allow for long-term session persistence, but in an agentic world, this creates a risk of zombie tokens—permissions that persist long after an agent should have been decommissioned. By forcing the agent to present a new ID-JAG to extend its access, the service provider maintains real-time control over the agent's lifecycle. This is paired with a precise revocation system where the `revocation_uri` can be used to target and kill specific delegation records based on the issuer (iss) and subject (sub) pair, rather than nuking a global API key.
To manage the operational overhead of these agents, the protocol recommends a Just-In-Time (JIT) provisioning sequence. When an agent connects, the server first attempts to match the `iss` and `sub` pair against existing delegation records, then checks the verified email, and finally performs JIT provisioning to create a new account if permitted by policy. To ensure full visibility, the protocol mandates a standardized set of audit events: `registration.created`, `claim.requested`, `otp.generated`, `claim.confirmed`, `registration.expired`, and `registration.revoked`. For ID-JAG flows, these logs must include the `iss`, `sub`, and `agent_platform` to allow for cross-platform correlation during security audits.
Developers can explore the full implementation and technical specifications through the Repo and the Technical details documentation.
This transition from human-managed secrets to machine-readable identity protocols marks the end of the manual onboarding era for AI agents.
