Get started
Authentication
One bearer key per account, KYB verification on the operations that expose enforcement data, and a 401 that means something different from a 403.
The header
Every request carries the key as a bearer token.
GET /v1/coverage HTTP/1.1
Host: api.foreshock.org
Authorization: Bearer fsk_EXAMPLE_0000000000000000
Accept: application/jsonKeys are secrets. Keep them out of source control, out of query strings, and out of logs.
Key scope
A key is scoped to a single customer account. Cross-customer reads are not expressible rather than merely denied: customer_id is the leading key column and partition key of every customer data table, so a key cannot address another account’s data even in principle.
KYB-gated operations
Operations marked x-kyb-required: true in the contract additionally require the account to have completed institutional KYB verification. In v1 that is GET /v1/exposure, GET /v1/coverage, and POST /v1/decide/deposit.
Enforcement data in a non-terminal stage is not available to unverified accounts under any plan. That is a product boundary, not a pricing tier.
401 and 403 are different, and the difference matters
| Status | type | What it means | What to do |
|---|---|---|---|
401 | .../unauthorized | The key is missing, malformed, or revoked. | Stop. Do not retry with the same key. Page someone. |
403 | .../kyb-required | The key is valid; the account has not completed KYB. | Stop. This will not resolve by retrying. |
403 | .../forbidden | The key is valid but not entitled to this specific resource. | Check that the resource belongs to this account. |
A valid key on a non-verified account receives 403, not 401. If your client collapses both into “auth failed and retry”, it will retry forever against a condition that only a human can clear.
Handling a rejected key on the decision path
An auth failure on POST /v1/decide/deposit is not a verdict. There is no verdict in any non-2xx response. Whatever the status code, the deposit stays on HOLD until a 200 arrives.