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.

How does a bot prove its identity without a shared secret?

Via Web Bot Auth (RFC 9421 HTTP Message Signatures). A bot signs its outbound requests with an Ed25519 key and a Signature-Agent header, and publishes the matching public keys as a JWK Set at /.well-known/http-message-signatures-directory. An origin can then verify the signature and distinguish a genuine agent from a spoofed User-Agent — no shared secret required. Agent Ready publishes its own directory at https://agent-ready.dev/.well-known/http-message-signatures-directory and scores any site for it via check C14. Web Bot Auth identifies the bot; the Bearer API key authorises the call — the two are complementary, not alternatives.

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.

Authentication models: M2M, client credentials, and bots

Agent Ready is built for unattended workloads, so its authentication is machine-to-machine first. Two complementary models apply.

Machine-to-machine (M2M) Bearer keys — the client-credentials model

The Agent Ready API key is a machine-to-machine (M2M) credential: it authenticates a headless workload, not an interactive human session. That is precisely the role of the OAuth 2.0 client-credentials grant (grant_type=client_credentials) — a no-human-in-the-loop flow for daemons, agents, and CI jobs. The only difference is issuance: rather than exchanging a client_id / client_secret pair at a token endpoint for a short-lived access token, Agent Ready issues the long-lived Bearer key directly from the dashboard and you present it on every request. The practical contract is the same one your agent runtime already expects: one secret in a secret manager, Authorization: Bearer on every call, no browser redirect.

Bot authentication — Web Bot Auth (RFC 9421)

When a bot needs to prove which agent it is — not just carry a shared secret — it uses Web Bot Auth. The bot signs its outbound requests with an Ed25519 key under RFC 9421 HTTP Message Signatures and a Signature-Agent header, publishing its public keys as a JWK Set at /.well-known/http-message-signatures-directory. An origin can then tell a genuine agent from a spoofed User-Agent without any pre-shared credential. Agent Ready publishes its own directory at /.well-known/http-message-signatures-directory and scores any site for it via check C14. Web Bot Auth identifies the bot; the Bearer key authorises the call — use them together.

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.
Does Agent Ready support machine-to-machine (M2M) / client-credentials authentication?: Yes. The Bearer API key is a machine-to-machine (M2M) credential — it authenticates a headless workload, not an interactive human session, which is exactly what the OAuth 2.0 client-credentials grant (grant_type=client_credentials) is for. The only difference is issuance: instead of exchanging a client_id/client_secret pair at a token endpoint for a short-lived access token, Agent Ready issues the long-lived Bearer key directly from the dashboard and you present it on every request. For agent, bot, and CI/CD workloads the practical contract is identical — one secret in your secret manager, Authorization: Bearer on every call, no browser redirect and no human in the loop at call time.
How does a bot prove its identity without a shared secret?: Via Web Bot Auth (RFC 9421 HTTP Message Signatures). A bot signs its outbound requests with an Ed25519 key and a Signature-Agent header, and publishes the matching public keys as a JWK Set at /.well-known/http-message-signatures-directory. An origin can then verify the signature and distinguish a genuine agent from a spoofed User-Agent — no shared secret required. Agent Ready publishes its own directory at https://agent-ready.dev/.well-known/http-message-signatures-directory and scores any site for it via check C14. Web Bot Auth identifies the bot; the Bearer API key authorises the call — the two are complementary, not alternatives.
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.