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

# Authentication

> API keys and OAuth for the PolyTape agent plane — minting, header usage, key limits per plan, and what a key can and cannot do.

Two credential families. Both are **header-only**, and both draw on **one
per-user budget**.

## API keys

```http theme={null}
Authorization: Bearer td_live_...
```

Mint a key in the dashboard: **AI Agents & API → Patch Bay**.

<Steps>
  <Step title="Open the Patch Bay">
    Dashboard → **AI Agents & API**. The Patch Bay is the rear panel where your
    ports live.
  </Step>

  <Step title="Mint">
    Give the key a label — one per agent or machine, so you can unplug one
    without disturbing the others.
  </Step>

  <Step title="Copy it now">
    The plaintext `td_live_` token exists **exactly once**, in the mint response.
    We store only its hash and the last four characters for display. It cannot be
    shown again.
  </Step>
</Steps>

<Warning>
  If you lose a key, you cannot recover it. Revoke it and mint a new one.
</Warning>

### Rules that bite

* **Header only.** A key is never accepted in a query string. A key in a URL is a
  key in an access log.
* **Revocation is instant.** A revoked key fails on its very next call — there is
  no cache to wait out. Plan downgrades bite the next request too.
* **Keys are cables, not quota.** Every key you own spends from the same call
  budget. A second key gives you a second plug, not a second allowance.

### Ports per plan

| Plan                      | API keys |
| ------------------------- | -------- |
| Basic Intelligence (free) | 1        |
| Pro Intelligence          | 3        |
| Max Intelligence          | 6        |

The cap counts **non-revoked** keys. Minting past it returns `402` with a message
naming your plan's limit — unplug a key or upgrade.

## OAuth (MCP)

Some MCP clients — the claude.ai custom connector, Claude Code, Cursor,
opencode — can connect over OAuth instead of a pasted key. You sign in with your
PolyTape account and consent; the client handles tokens from there. No key
material is ever pasted or stored in a config file.

The connect panel in the dashboard shows the exact per-client steps and whether
OAuth is live for your client yet. Where it is not, the key + `Authorization:
Bearer` path always works.

<Note>
  OAuth sessions and API keys spend from the **same** per-user budget. Connecting
  a different way does not get you a separate allowance.
</Note>

## What a key can and cannot do

<Columns cols={2}>
  <Card title="Can" icon="check">
    Read everything on this API — traders, markets, fills, tapes, the popular
    shelf — and open live agent streams for wallets. All read-only.
  </Card>

  <Card title="Cannot" icon="xmark">
    Mint or manage keys (a dashboard action, never an API-key action), write
    anything, or place a trade. V1 is read-only by construction.
  </Card>
</Columns>

## Auth failures

| HTTP | error                    | meaning                                                                       |
| ---- | ------------------------ | ----------------------------------------------------------------------------- |
| 401  | `missing_credentials`    | no `Authorization` header                                                     |
| 401  | `invalid_api_key`        | unknown or revoked key                                                        |
| 429  | `too_many_auth_failures` | too many bad keys from your IP — fix the credential, then wait out the window |

401s carry a `WWW-Authenticate: Bearer` header. See [Errors](/errors) for the
full table.