Keys and scopes
Every request carries your business's API key in the Authorization header:
Authorization: Bearer ocost_sk_<id>_<secret>curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY"import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()const files = await fetch('https://api.ocost.io/public/v1/files', {
headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());Keys
- PrefixSecret scanners spot it in a leak.
- Public idNot secret. Settings lists keys by it.
- SecretShown once. Keep it on your server.
Authorization: Bearer ocost_sk_…- Every request
Ocost-Business: <id>- A company of the group, optional
The owner or the accountant makes keys under Settings › Developers. 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.
Caution
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.
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
-H "Ocost-Business: $COMPANY_ID"files = session.get(
"https://api.ocost.io/public/v1/files",
headers={"Ocost-Business": company_id},
timeout=15,
).json()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 says how a key reaches several companies and where its files land.
Rotate a key
- Make a new key with the same scopes.
- Switch your software to it.
- 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 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. |