Authentication - Augment External API

API key header

Send your API key on every request in the x-api-key header:

x-api-key: <your-api-key>

Requests with a missing, unrecognised, or revoked key are rejected with a 401 response.

Unauthenticated endpoint

GET /api/v1/health is the one exception: it takes no key and returns no scope requirement, so a caller can tell an outage apart from a credential problem.

401 — authentication errors

`code`	Meaning
`unauthenticated`	No API key was sent
`invalid_key`	The key is not recognised
`key_revoked`	The key has been revoked

Scopes

Every API key is granted one or more scopes. An endpoint that requires a scope your key does not have returns 403 insufficient_scope.

Scope	Required by
`read:companies`	`GET /api/v1/companies`, `GET /api/v1/companies/{company_id}`
`read:offerings`	`GET /api/v1/offerings`, `GET /api/v1/offerings/{offering_id}`

GET /api/v1/health requires no scope.

403 — authorization errors

`code`	Meaning
`insufficient_scope`	The API key lacks the scope the endpoint requires
`client_suspended`	The API client is suspended

⌘I