Does Agent Ready support OAuth 2.1 authorization code flow?

Not yet. The /.well-known/oauth-protected-resource document advertises Bearer token semantics per RFC 9728, but the only issuance path today is the human-mediated dashboard. If you need authorization code flow or dynamic client registration for an MCP gateway or agent platform, open an issue describing the integration — we'll prioritise based on demand.

Where does agent_auth fit in?

agent_auth is the umbrella term for the emerging set of patterns that let an autonomous agent acquire and present credentials to a third-party API on a human user's behalf. The WorkOS auth.md spec collects the conventions (register_uri, identity_assertion, id-jag, WWW-Authenticate-driven discovery). Agent Ready's current API key surface is a strict subset — Bearer tokens with WWW-Authenticate discovery — and we will expand toward the fuller spec as agent runtimes standardise.

What is the difference between an API key and an identity_assertion token?

An API key is a long-lived shared secret that authenticates the bearer. An identity_assertion is a short-lived, audience-scoped token (often an id-jag — id-jWT-assertion-grant) minted by an upstream identity provider that proves which human a request is acting on behalf of. Agent Ready accepts only API keys today; identity_assertion support depends on an IdP integration that maps assertions to billing accounts, which is on the roadmap rather than shipped.

Can the same key be used for REST and MCP?

Yes — both surfaces accept the same Bearer key and share the same per-minute / per-day rate-limit budget. There is no separate "mcp_token" concept. A key created at /dashboard/api-keys works against POST /api/v1/scans and POST /api/v1/mcp interchangeably.

How do I rotate a key without downtime?

Create a new key, deploy it to your secret manager, restart the agent (or wait for it to read the new value at next request), then revoke the old key. Because keys are independent (not versioned), the old and new keys coexist until you delete the old one — overlapping windows of any length are fine.

Agent authentication for Agent Ready

What is agent_auth?

agent_auth is the umbrella term for the patterns AI agents use to acquire and present credentials to third-party APIs. The conventions — register_uri for dynamic client registration, identity_assertion and id-jag for short-lived tokens minted by an upstream identity provider, and WWW-Authenticate-driven discovery — are collected in the WorkOS auth.md draft. Agent Ready supports the subset needed for Bearer-token API access today; the rest will follow as agent runtimes standardise.

Step 1 — Discover the auth endpoint

Every agent_auth flow starts with the protected resource advertising how it should be talked to. Agent Ready publishes that document at /.well-known/oauth-protected-resource per RFC 9728. Fetch it cold or follow the WWW-Authenticate header returned on any 401 response — both routes land in the same place.

curl -s https://agent-ready.dev/.well-known/oauth-protected-resource | jq

Step 2 — Pick a method

Agent Ready offers a single credential type today: a long-lived Bearer API key issued from the human-owned dashboard. There is no dynamic client registration (register_uri) yet and no identity_assertion / id-jag token-exchange flow. The surface is intentionally minimal — pick the Bearer token method, register a key (Step 3), and move on. If your agent runtime expects OAuth 2.1 authorization code flow, open an issue describing the integration.

Step 3 — Register your agent

Sign in at /sign-in with the human operator's account, then open /dashboard/api-keys. Click Create key, name the key after the agent or workload that will use it, and copy the secret. The secret is shown once. Store it in your agent's secret manager (1Password, Doppler, AWS Secrets Manager, GitHub Actions secrets) — never commit it to a repo.

Pro plan required. Free-tier accounts can sign up and view the page but cannot mint a key.

Step 4 — Claim a credential

There is no separate claim step today — the Bearer key is the credential, issued at creation time. The claim phase is reserved for a future identity_assertion flow where an upstream IdP mints a short-lived id-jag that Agent Ready exchanges for an access token. When that ships, this section will describe the exchange contract.

Step 5 — Use the credential

Send every request with the Authorization: Bearer <key> header. The same token authenticates REST (POST /api/v1/scans, GET /api/v1/scans/{id}, POST /api/v1/ask) and the MCP endpoint (POST /api/v1/mcp). Treat it like a password: TLS only, never in URLs or logs.

curl -X POST https://agent-ready.dev/api/v1/scans \
  -H "Authorization: Bearer $AGENT_READY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Step 6 — Handle errors

401 Unauthorized. Missing or invalid Bearer token. The response carries a WWW-Authenticate header pointing at the discovery document so a fresh agent can recover without prior knowledge.
403 Forbidden. Authenticated but the plan tier doesn't allow this endpoint (e.g. Free-tier key calling /api/v1/scans).
429 Too Many Requests. Over the per-minute (10) or per-day (200) rate limit. The response carries a Retry-After header.
400 Bad Request. Validation error — the JSON body names the offending field.

HTTP/2 401
content-type: application/json
www-authenticate: Bearer realm="agent-ready", resource_metadata="https://agent-ready.dev/.well-known/oauth-protected-resource"

{"error":"unauthorized","message":"Missing or invalid Bearer token"}

Step 7 — Revoke a credential

Revoke a key from /dashboard/api-keys. Click the delete icon next to the row; the key is invalidated immediately. Any subsequent request returns 401. If a key is suspected leaked, revoke first, then rotate the replacement into your secret manager before redeploying. Revocation is instant and irreversible — there is no soft-expiry grace window.

Frequently asked questions

Does Agent Ready support OAuth 2.1 authorization code flow?: Not yet. The /.well-known/oauth-protected-resource document advertises Bearer token semantics per RFC 9728, but the only issuance path today is the human-mediated dashboard. If you need authorization code flow or dynamic client registration for an MCP gateway or agent platform, open an issue describing the integration — we'll prioritise based on demand.
Where does agent_auth fit in?: agent_auth is the umbrella term for the emerging set of patterns that let an autonomous agent acquire and present credentials to a third-party API on a human user's behalf. The WorkOS auth.md spec collects the conventions (register_uri, identity_assertion, id-jag, WWW-Authenticate-driven discovery). Agent Ready's current API key surface is a strict subset — Bearer tokens with WWW-Authenticate discovery — and we will expand toward the fuller spec as agent runtimes standardise.
What is the difference between an API key and an identity_assertion token?: An API key is a long-lived shared secret that authenticates the bearer. An identity_assertion is a short-lived, audience-scoped token (often an id-jag — id-jWT-assertion-grant) minted by an upstream identity provider that proves which human a request is acting on behalf of. Agent Ready accepts only API keys today; identity_assertion support depends on an IdP integration that maps assertions to billing accounts, which is on the roadmap rather than shipped.
Can the same key be used for REST and MCP?: Yes — both surfaces accept the same Bearer key and share the same per-minute / per-day rate-limit budget. There is no separate "mcp_token" concept. A key created at /dashboard/api-keys works against POST /api/v1/scans and POST /api/v1/mcp interchangeably.
How do I rotate a key without downtime?: Create a new key, deploy it to your secret manager, restart the agent (or wait for it to read the new value at next request), then revoke the old key. Because keys are independent (not versioned), the old and new keys coexist until you delete the old one — overlapping windows of any length are fine.