Keys and scopes

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

Text
Authorization: Bearer ocost_sk_<id>_<secret>
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"

Keys

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.

Text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"

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

  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.

ScopeAllows
documents:writePOST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, the MCP tool send_file
documents:readGET /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:readGET /public/v1/search, and the MCP's search tools
figures:readThe MCP's figures tools. Only the owner makes a key with it.
exports:writeThe 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

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

See also