API Key vs OAuth — Which to use

When to authenticate with an X-API-Key vs the OAuth 2.1 flow.

AGO’s Public API v1 supports two authentication methods. Both grant the same scope-based permissions; they differ in how credentials are issued and rotated.

Quick guide

You are…	Use
A developer writing scripts, integrations, or backend services	X-API-Key
A user connecting Claude Web, ChatGPT MCP, Cursor, or another MCP client	OAuth
Building an SDK that ships to many users (each user authenticates as themselves)	OAuth
Running CI/CD that needs to call the AGO API	X-API-Key (created by an admin, scoped to the right action)

How they differ

	X-API-Key	OAuth (authorization-code + PKCE)
Identity	Service identity (no user)	User identity (token tied to the user who consented)
Issued by	Admin via dashboard	User self-grants via consent screen
Header	X-API-Key: ago_v1_sk_...	Authorization: Bearer ...
TTL	None (long-lived)	1 hour access; 30-day refresh
Rotation	Manual via admin (24 h grace)	Automatic on refresh
Revocation	Admin clicks Revoke	Admin or user clicks Revoke
Audit row	API key identity captured	OAuth token, application, and consenting user captured
IP allowlist	Yes	No (tied to user, not IP)

Migration

Existing X-API-Key integrations stay as-is — there is no deprecation path. The two methods coexist and can be used by different consumers of the same tenant.

If you previously used Claude Desktop with an X-API-Key proxy and want to switch to Claude Web’s native OAuth: keep your API key for backend scripts, and follow Connect Claude Web to AGO to add OAuth alongside.

Why does Claude Web need OAuth?

Claude Web’s custom-connector UI doesn’t accept arbitrary HTTP headers — it only passes Authorization: Bearer <token>. An X-API-Key header would be silently dropped, so Claude Web requires OAuth or no auth. The desktop app supports custom headers because users edit a local config file directly.

Both methods enforce scopes the same way

Whatever the auth method, every Public API endpoint checks that the credential carries the required scope. A request without it returns 403 Forbidden. Available scopes are listed in your tenant’s /.well-known/oauth-authorization-server document and shown on the consent screen.