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

# Authentication

> Connect to the SmartAlex MCP server with an API key or OAuth 2.0, understand read vs write scopes, and know the rate limits.

The cloud MCP server accepts two kinds of credential on the `Authorization: Bearer` header: a **SmartAlex API key** or an **OAuth 2.0** token. Pick whichever your client supports.

| Method        | Best for                                                                        |
| ------------- | ------------------------------------------------------------------------------- |
| **API key**   | Local installs (npm / stdio), scripts, and any client where you paste a token   |
| **OAuth 2.0** | Hosted clients (ChatGPT, Claude) that connect by URL and approve in the browser |

## API keys

Keys come in two environments:

| Prefix     | Environment       |
| ---------- | ----------------- |
| `sa_live_` | Live / production |
| `sa_test_` | Test / sandbox    |

A key is shown to you **once**, at creation. We store only a hash, never the raw key, so if you lose it you generate a new one rather than looking it up.

### Generating a key

<Steps>
  <Step title="Open the Developer Portal">
    Go to [**/developers**](https://app.getsmartalex.com/developers) and open the **API Keys** tab.
  </Step>

  <Step title="Create a key">
    Click **Create API Key**, choose the environment (live or test) and the scope, and copy the key immediately.
  </Step>

  <Step title="Store it securely">
    Put it in your client config or a secrets manager. You won't see it again.
  </Step>
</Steps>

<Note>
  Key generation requires the **Power Tools** add-on and a **super-admin** role on the workspace. If you don't see the Developer Portal, check both.
</Note>

### Scopes

| Scope   | Grants                                                                   |
| ------- | ------------------------------------------------------------------------ |
| `read`  | View contacts, agents, campaigns, calls (the default if no scope is set) |
| `write` | Create and update records                                                |

A key without `write` that calls a write tool gets a `403`, so scope your keys to what each client needs.

## OAuth 2.0

For hosted clients, connect by URL and authorise in your browser, no key to copy. The server implements the standard discovery flow, so a compliant client sets itself up automatically:

```mermaid theme={null}
sequenceDiagram
    participant C as AI client
    participant M as SmartAlex MCP
    participant B as Your browser

    C->>M: Connect (no token)
    M-->>C: 401 + pointer to metadata
    C->>M: Fetch protected-resource metadata
    M-->>C: Authorization server + scopes
    C->>B: Open approval page
    B-->>C: You approve
    C->>M: Retry with token
    M-->>C: Connected
```

Under the hood:

* **Protected-resource metadata** (RFC 9728) is served at `/.well-known/oauth-protected-resource`, so the client discovers where to authenticate.
* **Authorization-server metadata** (RFC 8414) is served at `/.well-known/oauth-authorization-server`, advertising the authorize and token endpoints, dynamic client registration, and **PKCE** (`S256`, required).
* A missing or invalid token returns `401` with a `WWW-Authenticate` header pointing back to the metadata, which is how the client knows to start the flow.

In practice you paste the MCP URL into your client, it opens a browser approval, and you're connected.

## Rate limits

| Transport             | Limit              | Keyed by   |
| --------------------- | ------------------ | ---------- |
| Cloud (authenticated) | 100 requests / min | Workspace  |
| Public (onboarding)   | 30 requests / min  | IP address |

Over the limit returns `429` with a `Retry-After` header and `X-RateLimit-*` headers; well-behaved clients back off automatically. If you drive the REST API directly with an `sa_` key, that path has its own per-key limit (default 60 / min, adjustable when you create the key).

<CardGroup cols={2}>
  <Card title="Local install (npm)" href="/mcp/npm-package">
    Set an API key for a stdio client.
  </Card>

  <Card title="Error reference" href="/mcp/errors">
    Every auth and rate-limit error, with fixes.
  </Card>
</CardGroup>