> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/agent/connect-claude-web) 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.