Authentication
The API key header, where keys come from, and what a refused key looks like.
API keys
Every call carries your API key in the X-Api-Key header.
| Key starts with | Environment |
|---|---|
fs_test_ | Sandbox |
fs_live_ | Production |
Both kinds of key call the same address; the key decides the environment. Create keys in the FinSour console.
Keep keys on your server
Keys are for calls from your own server. A request that carries a key and a browser’s Origin header is refused 401 AUTH_KEY_INVALID, so a key cannot be used from a web page even by accident. A key can also be limited to an allowlist of addresses; a call from anywhere else is refused 403 AUTH_IP_NOT_ALLOWED.
When a key is refused
An invalid, revoked and expired key all answer with the same message, on purpose: the body does not tell anyone holding a key which of the three it is.
| Code | Status | Meaning | Retrying |
|---|---|---|---|
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
Written from FinSour platform API contract (finsour development at 80e8b83bf), last changed . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.