Authentication
Every request carries an API key as a bearer token. Keys are scoped, rate limited per credential, and metered per organization.
Bearer tokens
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.
| Prefix | Reads | Billed |
|---|---|---|
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. |
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.
| Scope | Grants |
|---|---|
opportunities:read | GET /opportunities |
eligibility:execute | POST /eligibility/evaluate |
usage:read | GET /usage |
webhooks:manage | GET 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.
| Limit | Window | Applies to |
|---|---|---|
| 120 requests | Per minute | Per credential, after the key is verified. This is your throughput. |
| 60 requests | Per minute | Per 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.
| Situation | Result |
|---|---|
| Same key, same body, first call finished | The original response is replayed. The work is not repeated and you are not charged twice. |
| Same key, different body | 409 IDEMPOTENCY_CONFLICT. Two different requests are using one name. Use a fresh key for the genuinely different call. |
| Same key, first call still running | Also 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 key | The 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.
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.
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.