# Keys and scopes
> API keys: how a request carries one, rotating them, their scopes, and the refusals.

Every request carries your business's API key in the `Authorization` header:

```text
Authorization: Bearer ocost_sk_<id>_<secret>
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
```

## Keys

The owner or the accountant makes keys under [Settings › Developers](https://app.ocost.io/settings/api). Ocost shows a key once and keeps only a fingerprint. If you lose a key, revoke it and make a new one.

The start of a key, `ocost_sk_<id>_`, isn't secret. Settings lists keys by it, with their scopes and last use. Secret scanners spot the `ocost_sk_` prefix in a leak.

A key belongs to the business it was made in. A business has at most 10 live keys. A key can also expire on a date.

> [!WARNING]
> Keep keys on your server. Never put one in a browser, a mobile app or a log.

## Companies of a group

The owner of a group of companies may give a key more of them under Settings › Developers. A key then reaches all of them, those added later too, or a selection. Ocost's support can set them too. Each change shows under Settings as a visit from Ocost.

`GET /public/v1/businesses` lists the companies a key reaches, its own first. Every key may ask it.

Name the company a request acts in with the `Ocost-Business` header, its id. Without it, the request acts in the key's own business.

```text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"
```

```python
files = session.get(
    "https://api.ocost.io/public/v1/files",
    headers={"Ocost-Business": company_id},
    timeout=15,
).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}`, 'Ocost-Business': companyId },
}).then((r) => r.json());
```

The key and its secret stay the same when its companies change. A company it no longer reaches is refused from the next request. So is a company that leaves the group.

[Company groups](https://ocost.io/docs/en/groups.md) says how a key reaches several companies and where its files land.

## Rotate a key

1. Make a new key with the same scopes.
2. Switch your software to it.
3. Revoke the old key. Ocost refuses it from the very next request.

## Scopes

A key may do only what its scopes allow. Settings › Developers ticks the first three for a new key.

| Scope | Allows |
| --- | --- |
| `documents:write` | `POST /public/v1/files`, `DELETE /public/v1/files/{file_id}`, `PATCH /public/v1/files/{file_id}`, the MCP tool `send_file` |
| `documents:read` | `GET /public/v1/files`, `GET /public/v1/files/{file_id}`, `GET /public/v1/files/{file_id}/content`, `GET /public/v1/files/{file_id}/document`, `GET /public/v1/documents/{document_id}`, and the MCP tools that read records |
| `search:read` | `GET /public/v1/search`, and the MCP's search tools |
| `figures:read` | The MCP's figures tools. Only the owner makes a key with it. |
| `exports:write` | The MCP's export tools |

[MCP tools](https://ocost.io/docs/en/tools.md) lists each tool under its scope.

No key ever reads people's papers, such as pay slips, payroll or health papers.

## Refusals

| Answer | When |
| --- | --- |
| `401 urn:ocost:key:invalid` | No key, or a malformed, wrong, revoked or expired one, or a deleted business's. The answer is always the same. |
| `403 urn:ocost:key:scope` | The key lacks the route's scope. |
| `403 urn:ocost:key:business` | The key doesn't reach the company `Ocost-Business` names. |
| `400 urn:ocost:key:business` | `Ocost-Business` isn't a company's id. |
| `429 urn:ocost:key:rate` | Too many requests, or too many wrong keys from one address. Wait `Retry-After` seconds. |
| `400` | The request has an `Ocost-View…` header, which only Ocost's web app sends. |

## See also

- [Company groups](https://ocost.io/docs/en/groups.md): Company groups: which companies a key reaches, the Ocost-Business header, routing by the document’s identifiers, needs_company, and files across the group.
- [Limits and errors](https://ocost.io/docs/en/limits.md): The plan's documents a month, rate limits, sizes, RFC 9457 errors, retrying, and where the data is kept.
- [Connect an assistant](https://ocost.io/docs/en/mcp.md): Connect an assistant to the MCP server (https://api.ocost.io/public/mcp, the same keys): Claude Code, Claude Desktop, Cursor, claude.ai and ChatGPT through OAuth, and any client.
- On ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
