Skip to content

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 withEnvironment
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.

CodeStatusMeaningRetrying
AUTH_KEY_EXPIRED401The API key is not valid.Do not retry automatically
AUTH_KEY_INVALID401The API key is not valid.Do not retry automatically
AUTH_KEY_MISSING401No API key was presented.Do not retry automatically
AUTH_KEY_REVOKED401The API key is not valid.Do not retry automatically
AUTH_IP_NOT_ALLOWED403This API key may not be used from this address.Do not retry automatically
ENTITLEMENT_MISSING403This organization is not entitled to that product in this environment.Do not retry automatically
ORGANIZATION_SUSPENDED403This organization is not active.Do not retry automatically
SCOPE_INSUFFICIENT403This 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.