Authentication

Every request carries an API key as a bearer token. Keys are scoped, rate limited per credential, and metered per organization.

Bearer tokens

Header
Authorization: Bearer gfin_live_4f2b18c7a93e5d016b8c2f7a41d9e30582bc6a17

Send the key over HTTPS only. It is a credential in the same class as a password: never in a query string, never in client-side code, never committed.

Key format

Keys match gfin_(live|test)_ followed by 40 hexadecimal characters. The format is checked before the key is looked up, so a malformed key is rejected without a database call and cannot be used to probe which keys exist.

Test and live key prefixes
PrefixReadsBilled
gfin_live_The real catalog.Yes, against your organization quota.
gfin_test_Synthetic sandbox fixtures only. Never real data.No. Recorded, never billed, never counted against quota.
The environment is a property of the credential. There is no request parameter or header that moves a live key into the sandbox, and no way for a test key to reach real data.

Scopes

A key carries an explicit list of scopes. Calling an operation your key does not cover is 403 INSUFFICIENT_SCOPE, which is a permanent answer: retrying will not change it, and the fix is a new key with the scope you need.

Scopes and the operations they grant
ScopeGrants
opportunities:readGET /opportunities
eligibility:executePOST /eligibility/evaluate
usage:readGET /usage
webhooks:manageGET and POST /webhook-endpoints

GET /ping requires no scope. Any valid key may test itself, which is what makes it a usable diagnostic.

Rate limits

Two limits apply, and they exist for different reasons.

Rate limits
LimitWindowApplies to
120 requestsPer minutePer credential, after the key is verified. This is your throughput.
60 requestsPer minutePer IP address, before any key is verified. This exists to stop key guessing, not to limit you.

Exceeding either is 429 RATE_LIMITED. It is transient and safe to retry after a backoff. Honour Retry-After when present rather than retrying immediately.

429 has two distinct causes and they need opposite handling. RATE_LIMITED is a short-term ceiling: back off and retry. QUOTA_EXCEEDED is your monthly allowance being spent: retrying cannot restore it, and a client that retries into a quota error just burns its own time. Branch on code, not on the status.

Quotas

Usage is metered per organization, not per key, so several credentials draw on one allowance. GET /usage reports what has been counted for the current period. Sandbox traffic is excluded from it, because that endpoint answers what is billable.

The response carries a top-level quota object when an organization-wide ceiling is configured: limit, used, remaining, and enforced. When no ceiling is configured, quota is null, which means “no ceiling set”, never “zero left”. enforced: false means the ceiling is reported but not yet blocking requests.

Per-meter included and remaining stay null: the allowance is organization-wide across every meter, so a per-meter number would be fabricated. The report and the enforcing gate read the same configuration, so what quota says and what a 429 QUOTA_EXCEEDED does can never disagree about the ceiling.

Idempotency

Send an Idempotency-Key header on every POST. Generate it once per logical call and reuse it for every retry of that call.

Replay is implemented for both live POSTs: POST /eligibility/evaluate and POST /webhook-endpoints. A replayed response carries an Idempotent-Replay: true header so you can tell it from fresh work. Endpoint creation is additionally guarded without a key: registering a URL your organization already has is 409 DUPLICATE_ENDPOINT, because two endpoints at one receiver would deliver every matching event twice.

Idempotency key behaviour
SituationResult
Same key, same body, first call finishedThe original response is replayed. The work is not repeated and you are not charged twice.
Same key, different body409 IDEMPOTENCY_CONFLICT. Two different requests are using one name. Use a fresh key for the genuinely different call.
Same key, first call still runningAlso 409 IDEMPOTENCY_CONFLICT, but it means “in flight”, not “conflicting”. Wait and retry with the same key. Minting a fresh one here defeats the protection and can charge you twice, which is the exact harm the header exists to prevent.
No keyThe request executes normally. A retry after a lost response may duplicate the work.

Webhook signatures

Every delivery carries a GFIN-Signature header. Verify it before trusting the body.

Header
GFIN-Signature: t=1788000000,v1=dc2c7de20fbff43d8dee5e94be1ea41b1556115d7418e00b6698eda42fbb74c6

v1 is an HMAC-SHA256 over the exact string <t>.<raw body>, keyed with the endpoint secret returned once when you created the endpoint.

Verification requires both a matching MAC and a timestamp inside a five minute window. Both conditions matter: a signature proves who wrote the body, not when, and without the freshness check a delivery captured once can be replayed at you forever.

Verify against the raw request body, before any JSON parsing. If your framework parses the body and you re-serialize it, the bytes change and the signature will not match, which reads as an attack when it is really a framework doing its job.

Both SDKs ship a verifier that uses a constant-time comparison. Use it rather than ==, which leaks the expected MAC to anyone who can time your responses and retry.

Losing a key

A key is displayed once. We store a hash, so a lost key cannot be recovered: create a replacement and revoke the old one from Settings, API keys. Revocation takes effect on the next request, which then answers 401 INVALID_CREDENTIAL.