---
updatedAt: 2026-07-01T18:02:09.000Z
agentTools:
  projectIndex: https://docs.rocketreach.co/llms.txt
---

# Authentication

The RocketReach MCP server uses **OAuth 2.1 with PKCE** and **Dynamic Client Registration (DCR)**. MCP-compatible clients handle this flow automatically — you do not need to implement it yourself. This page documents the flow for developers building their own MCP clients or integrations.

## How it works

The server exposes a standard OAuth discovery chain that compliant clients follow automatically:

1. **Discovery** — the client fetches `/.well-known/oauth-protected-resource` from the MCP server to learn the authorization server URL.
2. **Authorization server metadata** — the client fetches `/.well-known/oauth-authorization-server` from the authorization server (RocketReach) to discover all OAuth endpoints.
3. **Dynamic Client Registration** — the client registers itself by POSTing to `/mcp-oauth/register` and receives a `client_id`.
4. **Authorization** — the client redirects the user's browser to `/mcp-oauth/authorize` with a PKCE `code_challenge`.
5. **User consent** — the user logs into RocketReach and approves the access request.
6. **Token exchange** — the client exchanges the authorization code for an access token via `POST /mcp-oauth/token`.
7. **API calls** — the client sends `Authorization: Bearer <token>` on every request to `POST /mcp`.

## Endpoints

| Step      | Endpoint                                                              | Notes                                                           |
| --------- | --------------------------------------------------------------------- | --------------------------------------------------------------- |
| Discovery | `GET https://mcp.rocketreach.co/.well-known/oauth-protected-resource` | Returns the resource identifier and its authorization server(s) |
| Register  | `POST https://rocketreach.co/mcp-oauth/register`                      | Dynamic Client Registration (RFC 7591)                          |
| Authorize | `GET https://rocketreach.co/mcp-oauth/authorize`                      | Redirect-based authorization with PKCE                          |
| Token     | `POST https://rocketreach.co/mcp-oauth/token`                         | Exchange code for access token                                  |

## Token format

Access tokens are **JWE-wrapped JWTs** (sign-then-encrypt). The outer envelope is AES-256-GCM (JWE); inside is an HS256-signed JWT (JWS) that carries standard claims (`sub`, `aud`, `exp`) plus RocketReach-specific claims including the API key. The inner JWS is signed, not encrypted, so the API key sits in plaintext inside it — the outer JWE envelope is what keeps these credentials confidential from intermediate parties.

Pass tokens as Bearer tokens:

```
Authorization: Bearer <access_token>
```

Tokens are bound to the MCP server URL — a token issued for `mcp.rocketreach.co` will be rejected by any other audience. The server validates the audience claim on every request.

## Token lifetimes

| Token type    | Lifetime | Notes                                |
| ------------- | -------- | ------------------------------------ |
| Access token  | 1 hour   | Bearer token sent with every request |
| Refresh token | 30 days  | Opaque string; rotates on each use   |

Access tokens are short-lived by design. When one expires, compliant MCP clients automatically exchange the refresh token for a new access + refresh token pair via `POST /mcp-oauth/token` with `grant_type=refresh_token`. This happens transparently — users are not prompted to re-authorize unless the refresh token itself expires or is revoked.

Refresh tokens are single-use and rotate on each exchange. If a refresh token is presented after already being used, all tokens for that user+client are immediately revoked.

## Token revocation

To disconnect an AI client or revoke a specific token:

```
POST https://rocketreach.co/mcp-oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_or_refresh_token>
```

Revoking a refresh token invalidates the access tokens issued from it.

## Scopes

A single scope is used: `rocketreach:read`. Authorizing this grants access to all tools (search, lookup, account). Pass it in the `scope` parameter of the authorization request, or omit it — an empty scope defaults to `rocketreach:read`.

## Custom client implementation notes

If you are building your own MCP client against the RocketReach OAuth endpoints:

* **Generate a random&#x20;**`state`**&#x20;parameter** before redirecting the user to `/mcp-oauth/authorize`. Verify the returned `state` matches on the callback. This is your CSRF defense for the OAuth flow — it is the client's responsibility, not the server's.
* **Dynamic Client Registration is open** per RFC 7591 — no pre-approval required. Register at `POST /mcp-oauth/register`.
* **Redirect URIs are bound at registration.** The `redirect_uri` on the authorize request must exactly match a URI registered for your `client_id`. Non-localhost redirects must use `https://`. `http://localhost` and `http://127.0.0.1` on any port are allowed for native/desktop clients (RFC 8252).

## Errors

| HTTP status | `error`                                            | Meaning                                                                                |
| ----------- | -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 400         | `invalid_scope`                                    | Scope other than `rocketreach:read` (or empty) was requested                           |
| 401         | `auth_required`                                    | No Bearer token in the request                                                         |
| 401         | `invalid_token`                                    | Token is expired, has the wrong audience, or was issued by an unrecognized server      |
| 401         | `invalid_token` (description: `decryption failed`) | Token was issued with a rotated-out encryption key — re-authorize to get a fresh token |

<br />