> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.1

> OAuth 2.1 authentication for browser MCP connectors such as Claude.ai and ChatGPT

The browser connectors in Claude.ai and ChatGPT do not accept an API key directly. They require **OAuth authentication**. Chainshift provides an OAuth 2.1 Authorization Server for this purpose (PKCE + Dynamic Client Registration).

> [!NOTE]
>
> The connector handles the OAuth flow (discovery, client registration, and
> token exchange) automatically. All you need to do is **paste your organization
> API key on the consent screen**.

## How to connect

**1. Add the MCP connector**

In the connector settings, enter the Chainshift MCP server URL.

```
https://dev-platform-api.trychainshift.ai/mcp
```

**2. Start authentication**

The connector detects that authentication is required and opens the Chainshift approval screen in your browser. Discovery and client registration happen automatically.

**3. Paste your API key**

Paste your organization API key (`cs_live_…`) into the approval screen and click **Approve**.

**4. Done**

The connector receives an access token and uses it automatically for subsequent requests. You can keep using it without re-authenticating.

The issued token is **bound to the API key** you pasted. If you revoke that API key in the dashboard, the linked OAuth token is invalidated immediately.

## Technical specifications

Most connectors perform the flow below automatically. Refer to this section only if you are implementing an OAuth client yourself.

> [accordion] Discovery endpoints
>
> * `GET /.well-known/oauth-protected-resource`: Protected Resource Metadata (RFC 9728)
> * `GET /.well-known/oauth-authorization-server`: Authorization Server Metadata (RFC 8414)
>
> An unauthenticated request to `/mcp` returns `401` with a `WWW-Authenticate: Bearer resource_metadata="…"` header, which tells the connector to start discovery.

> [accordion] Authentication flow
>
> 1. **Dynamic client registration**: `POST /oauth/register` (RFC 7591) → issues a `client_id`
> 2. **Authorization request**: `GET /oauth/authorize` (with a PKCE `code_challenge`) → renders the approval screen
> 3. **Authorization code issuance**: the user pastes an API key and approves → a one-time `code` is returned to the `redirect_uri`
> 4. **Token exchange**: `POST /oauth/token` (`grant_type=authorization_code`, `code_verifier`) → issues access and refresh tokens

> [accordion] Tokens and scopes
>
> | Item | Value |
> | - | - |
> | Access token | `cs_at_…` · valid for 1 hour |
> | Refresh token | `cs_rt_…` · valid for 30 days · rotated on use |
> | PKCE | `S256` only |
> | Scope | `mcp` |
>
> To refresh a token, call `POST /oauth/token` (`grant_type=refresh_token`, `refresh_token`, `client_id`). Refresh tokens are bound to the `client_id` they were issued to.

> [!TIP]
>
> For programmatic or CLI clients, it is simpler to use an [organization API key](https://dev-docs.trychainshift.ai/en/authentication/api-key.md)
> directly without OAuth. OAuth exists for browser connectors that do not accept
> an API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.