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

# OAuth Flow

> Authorize your Along account using OAuth 2.0 PKCE to connect to Claude, ChatGPT, or any MCP client.

Along uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) — no client secret required. This is the standard flow used by Claude and ChatGPT when you add a new MCP connector. Your credentials never leave Along's authorization server.

## Authorization server metadata

Any MCP client can discover Along's OAuth endpoints by fetching the well-known metadata document:

```text theme={null}
GET /.well-known/oauth-authorization-server
```

Response:

```json theme={null}
{
  "issuer": "https://along-api-qrd5m37v3a-ey.a.run.app",
  "authorization_endpoint": "https://along-api-qrd5m37v3a-ey.a.run.app/oauth/authorize",
  "token_endpoint": "https://along-api-qrd5m37v3a-ey.a.run.app/oauth/token",
  "registration_endpoint": "https://along-api-qrd5m37v3a-ey.a.run.app/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["vault:read", "vault:write"]
}
```

## Scopes

| Scope         | Description                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------- |
| `vault:read`  | Read access to the Safe's knowledge graph. Required for all MCP queries.                      |
| `vault:write` | Write access. Reserved for future use — `vault:read` is sufficient for all current MCP tools. |

## OAuth flow

<Steps>
  <Step title="Discovery">
    The MCP client fetches `/.well-known/oauth-authorization-server` to discover the authorization and token endpoints. This step is automatic for clients like Claude and ChatGPT.
  </Step>

  <Step title="Authorization request">
    The client redirects you to `GET /oauth/authorize` with the following parameters:

    | Parameter               | Required | Description                                                                        |
    | ----------------------- | -------- | ---------------------------------------------------------------------------------- |
    | `response_type`         | Yes      | Must be `code`                                                                     |
    | `client_id`             | Yes      | Your client ID, obtained from registration or auto-assigned                        |
    | `redirect_uri`          | Yes      | Must match a registered URI or a known pattern (claude.ai, chatgpt.com, localhost) |
    | `code_challenge`        | Yes      | SHA-256 of your `code_verifier`, base64url-encoded                                 |
    | `code_challenge_method` | Yes      | Must be `S256`                                                                     |
    | `scope`                 | No       | Defaults to `vault:read`                                                           |
    | `state`                 | No       | CSRF token; returned unchanged in the callback                                     |
    | `resource`              | No       | The MCP endpoint URL, e.g. `https://along-api-qrd5m37v3a-ey.a.run.app/mcp/v1`      |

    Example authorization URL:

    ```text theme={null}
    GET /oauth/authorize
      ?response_type=code
      &client_id=along_abc123
      &redirect_uri=https%3A%2F%2Fclaude.ai%2Fapi%2Fmcp%2Fauth_callback
      &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
      &code_challenge_method=S256
      &scope=vault%3Aread
      &state=xyz
    ```
  </Step>

  <Step title="User consent">
    Along redirects you to the Along app consent page. Log in with your Along account and optionally select a Safe to associate with this connection. Once you approve, Along returns an authorization `code` to the `redirect_uri`.

    The authorization code expires in **10 minutes**.
  </Step>

  <Step title="Token exchange">
    The client sends the authorization code to the token endpoint to receive access and refresh tokens:

    ```text theme={null}
    POST /oauth/token
    Content-Type: application/x-www-form-urlencoded

    grant_type=authorization_code
    &code=<authorization_code>
    &redirect_uri=https://claude.ai/api/mcp/auth_callback
    &code_verifier=<your_code_verifier>
    &client_id=along_abc123
    ```

    Response:

    ```json theme={null}
    {
      "access_token": "avo_...",
      "token_type": "Bearer",
      "expires_in": 3600,
      "refresh_token": "avr_...",
      "scope": "vault:read"
    }
    ```
  </Step>

  <Step title="Using the token">
    Include the access token as a Bearer token in all MCP requests:

    ```text theme={null}
    POST /mcp/v1
    Authorization: Bearer avo_...
    Content-Type: application/json
    ```
  </Step>
</Steps>

## Token lifetimes

| Token              | Lifetime                    |
| ------------------ | --------------------------- |
| Access token       | 1 hour (`expires_in: 3600`) |
| Refresh token      | 90 days                     |
| Authorization code | 10 minutes                  |

## Refreshing tokens

When an access token expires, the client exchanges the refresh token for a new access token and refresh token pair:

```text theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=avr_...
&client_id=along_abc123
```

The response has the same shape as the initial token response, with new `access_token` and `refresh_token` values. The old refresh token is revoked immediately after use.

## Client registration

For custom integrations that aren't Claude or ChatGPT, register your client before starting the OAuth flow:

```text theme={null}
POST /oauth/register
Content-Type: application/json

{
  "redirect_uris": ["https://myapp.example.com/oauth/callback"],
  "client_name": "My Integration",
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "none"
}
```

Response:

```json theme={null}
{
  "client_id": "along_...",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.example.com/oauth/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "none"
}
```

Use the returned `client_id` in all subsequent authorization requests.

<Note>
  Claude and ChatGPT auto-register as clients when they initiate the OAuth flow — you don't need to pre-register for those integrations.
</Note>