OAuth and auth.md

Agents First uses OAuth 2.1 with authorization code + PKCE (S256) for external agents. Clients can register dynamically, request workspace or agency access, refresh tokens, and revoke access when it is no longer needed.

Start with auth.md

Read auth.md for the agent-facing registration and authentication guide, including the CLI-first quickstart section.

For a standalone connect page (Claude Code, Codex CLI + config.toml, Claude web/Desktop, ChatGPT), use auth/connect.md. Both pages render from the same connect-copy source.

Discovery

For the MCP resource, clients should discover:

• Authorization server metadata: https://app.agentsfirst.ai/.well-known/oauth-authorization-server
• Protected resource metadata: https://app.agentsfirst.ai/.well-known/oauth-protected-resource/api/external-agent/mcp

The protected-resource metadata advertises resource_documentation at https://agentsfirst.ai/docs/external-agents/mcp (this public docs surface — unauthenticated).

OAuth lifecycle

1. Register a client at POST https://app.agentsfirst.ai/api/external-agent/oauth/register. 2. Send the operator to https://app.agentsfirst.ai/api/external-agent/oauth/authorize with PKCE and the requested resource. 3. Exchange the authorization code at https://app.agentsfirst.ai/api/external-agent/oauth/token. 4. Send the bearer token only to the authorized resource. 5. Revoke access at https://app.agentsfirst.ai/api/external-agent/oauth/revoke when the connection is no longer needed.

MCP clients that support protected-resource metadata normally complete these discovery steps automatically after you provide the MCP URL.