# auth.md

> Agent authentication and registration for Agents First SaaS.
> This file follows the auth.md convention (https://github.com/workos/auth.md).

## Audience

AI agents and autonomous clients that want to interact with the authenticated
Agents First SaaS control plane for a workspace or agency.

## Authenticated agent control plane — OAuth 2.1

To act on behalf of a workspace or agency (the Model Context Protocol control
plane and the workspace/agency REST APIs), register as an OAuth 2.1 client using
Dynamic Client Registration (RFC 7591). The lifecycle is:
**discover → register → authorize → use → revoke.**

1. **Discover** — read the canonical authorization-server metadata:
   https://app.agentsfirst.ai/.well-known/oauth-authorization-server/api/external-agent/oauth
   and the protected-resource metadata for the resource you need:
   https://app.agentsfirst.ai/.well-known/oauth-protected-resource/api/external-agent/mcp
   https://app.agentsfirst.ai/.well-known/oauth-protected-resource/api/workspace/v1
   https://app.agentsfirst.ai/.well-known/oauth-protected-resource/api/agency/v1

2. **Register** (Dynamic Client Registration):
   `POST https://app.agentsfirst.ai/api/external-agent/oauth/register`

3. **Authorize** (authorization code + PKCE / S256):
   https://app.agentsfirst.ai/api/external-agent/oauth/authorize

4. **Token / refresh**:
   https://app.agentsfirst.ai/api/external-agent/oauth/token

5. **Revoke**:
   https://app.agentsfirst.ai/api/external-agent/oauth/revoke

### Identity & credentials

- **Identity types:** `anonymous` — clients self-register via Dynamic Client
  Registration; no pre-verified human identity is required.
- **Credential types:** OAuth 2.1 client credentials issued at registration.
- **Grant types:** `authorization_code`, `refresh_token`.
- **Token endpoint auth:** `none` (public / PKCE clients), `client_secret_basic`,
  `client_secret_post`.
- **Bearer usage:** present access tokens in the `Authorization: Bearer <token>`
  header.

### MCP

The authenticated control-plane MCP protected-resource metadata is published at
https://app.agentsfirst.ai/.well-known/oauth-protected-resource/api/external-agent/mcp. The MCP
endpoint is https://app.agentsfirst.ai/api/external-agent/mcp (reachable once authorized).

## Quickstart — connect a client (CLI-first)

Connect any MCP-capable AI client to your Agents First workspace. Registration and sign-in are automatic OAuth 2.1 + PKCE — you approve once in your browser, and no token is ever pasted into a config file. CLI clients (Claude Code, Codex) are the fastest path; Claude web/Desktop and ChatGPT connect from their own UI.

**MCP server URL**

`https://app.agentsfirst.ai/api/external-agent/mcp`

Registration is automatic — no manual app setup. The primary path is a Client ID Metadata Document (CIMD): your client presents its hosted client-metadata URL as its client_id and this server registers it on the fly. Clients that don't support CIMD fall back automatically to Dynamic Client Registration (DCR). Either way you finish the same OAuth 2.1 + PKCE sign-in below.

### Claude (web, Desktop, mobile)

_Pro / Max / Team / Enterprise. On Team/Enterprise an Owner adds it in Organization settings._

1. Open Settings → Connectors (or Customize → Connectors).
2. Click “Add custom connector”.
3. Paste the MCP server URL below and click Add.
4. Click Connect, sign in to the portal, and Approve once — the button shows “Authorizing…”, no need to click twice.

### Claude Code (CLI)

_Any Claude Code install. Uses a loopback OAuth callback._

1. Run the command below to register the connector.
2. Start Claude Code and run /mcp, then choose Authenticate — your browser opens to the portal.
3. Approve once; the CLI captures the callback and stores the token.

```bash
claude mcp add --transport http agentsfirst https://app.agentsfirst.ai/api/external-agent/mcp
```

### ChatGPT (Developer Mode)

_Plus / Pro / Business / Enterprise / Edu (web). Admins enable Developer Mode for a workspace._

1. Settings → Apps → Advanced settings → enable Developer mode.
2. Settings → Apps & Connectors → Create.
3. Enter a name and paste the MCP server URL below; choose Authentication = OAuth.
4. Click Create, then complete the OAuth sign-in + single Approve.

### OpenAI Codex (CLI / IDE)

_Codex CLI and the IDE extension share config. Uses a loopback OAuth callback._

1. Run the two commands below (add, then login).
2. A browser opens to the portal; Approve once to mint the token.
3. Run /mcp inside Codex to confirm the connection is live.

```bash
codex mcp add agentsfirst --url https://app.agentsfirst.ai/api/external-agent/mcp
codex mcp login agentsfirst
```

Manual fallback — add this to `~/.codex/config.toml` if `codex mcp add` is unavailable (never put a bearer token in this file):

```toml
[mcp_servers.agentsfirst]
enabled = true
url = "https://app.agentsfirst.ai/api/external-agent/mcp"
oauth_resource = "https://app.agentsfirst.ai/api/external-agent/mcp"
```

Older Codex builds: if the connection does not start the OAuth login, add `experimental_use_rmcp_client = true` to ~/.codex/config.toml (newer builds enable the OAuth-capable MCP client automatically).

### First things to ask

- Give me a briefing on my workspace
- Triage my inbox
- Help me email my list

> Prefer a standalone page? The same quickstart lives at
> https://app.agentsfirst.ai/auth/connect.md, and the reference docs are at
> https://agentsfirst.ai/docs/external-agents/mcp.

## Contact

Questions: https://agentsfirst.ai/support