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

# API authentication

> How to authenticate API and MCP requests.

External integrations and MCP clients authenticate to the Blueprints API with a `bp_` API key:

```http theme={null}
Authorization: Bearer bp_YOUR_API_KEY
```

The web app uses a session cookie set by the in-product login flow. That cookie is browser-only — every programmatic caller (scripts, backends, MCP clients, scheduled jobs) must use an API key.

## API keys

API keys are scoped. A key can be broad enough to run a full MCP workflow, or narrow enough to only read blueprints or portfolio data. Treat a `bp_` key like a production credential: keep it server-side or inside trusted local MCP client configuration. Do not ship it in browser code, mobile apps, public repos, synced dotfiles, or frontend bundles.

Use API keys for:

* Remote MCP clients
* Backend services that read or update blueprints
* Internal tools that monitor orders, portfolio state, or risk rules
* Scheduled jobs that need account-scoped access

API keys are not shown again after creation. Store the key in your secret manager or local MCP client config immediately.

## API key scopes

| Scope               | Allows                                              |
| ------------------- | --------------------------------------------------- |
| `blueprints:read`   | List and read account blueprints                    |
| `blueprints:write`  | Create and edit draft blueprints                    |
| `blueprints:deploy` | Deploy, stop, and manually push blueprint nodes     |
| `orders:read`       | Read order activity                                 |
| `orders:write`      | Approve order intents                               |
| `portfolio:read`    | Read balances, positions, portfolio orders, and PnL |
| `portfolio:write`   | Close positions                                     |
| `risk:read`         | Read account risk rules                             |
| `risk:write`        | Update account risk rules                           |
| `api_keys:read`     | List API key metadata                               |
| `api_keys:write`    | Revoke API keys                                     |

Use explicit scopes for integrations. API keys cannot create other API keys, even when they have key-management scopes. Key creation requires an interactive web session in the Blueprints app.

## Managing keys

Create keys from the Blueprints app at [useblueprints.ai](https://useblueprints.ai). Listing keys requires `api_keys:read`. Revoking keys through the API requires `api_keys:write`, but API keys are never accepted by the create-key endpoint.

When rotating a key:

1. Create a replacement key in the app.
2. Update the integration or MCP client configuration.
3. Confirm the new key works.
4. Revoke the old key.

## Common auth failures

| Status | Meaning                                                      | Fix                                                                   |
| ------ | ------------------------------------------------------------ | --------------------------------------------------------------------- |
| `401`  | The bearer token is missing, expired, malformed, or revoked. | Check the `Authorization` header and rotate the credential if needed. |
| `403`  | The credential is valid but cannot perform this action.      | Add the required scope or use a different key.                        |
| `404`  | The resource does not exist for this account.                | Confirm the UUID belongs to the authenticated account.                |