Authentication
Bearer tokens over TLS 1.3. No OAuth dance, no request signing on the request path — the complexity is in scoping and rotation, which is where it belongs.
Keys
Authorization: Bearer ftai_live_7Kq2… // production, billed Authorization: Bearer ftai_test_9Bm4… // sandbox, never billed
Keys are shown once at creation and stored only as a hash. We cannot recover one for you. A live key and a test key are never interchangeable: a test key against the production host returns 401, which is deliberate — it means a misconfigured environment fails loudly rather than billing you.
Scopes
Scope each key to the least it needs. A key scoped to screen:read calling a credit endpoint gets 403 with code: "scope_insufficient".
| Scope | Grants |
|---|---|
| screen:read | Address and transaction screening, evidence retrieval |
| credit:read | CreditGraph profiles and point-in-time replay |
| route:quote | PayRoute quotes only — cannot execute |
| route:execute | PayRoute execution. Grant to as few keys as possible. |
| treasury:read | Ledger Mind reconciliation and policy events |
| treasury:write | Resolve exceptions, edit mappings |
| webhooks:manage | Create, update and delete webhook endpoints |
Separating route:quote from route:execute matters: quoting is safe to expose broadly across your services, executing moves money.
Rotation without downtime
Multiple keys may be active at once, which makes rotation a deploy rather than an outage.
1. Create the new key POST /v1/keys
2. Deploy it alongside the old one
3. Confirm traffic has moved GET /v1/keys // last_used_at
4. Revoke the old key DELETE /v1/keys/{id}
Revocation is immediate and global — there is no grace period and no cache to wait out. Rotate every 90 days, and immediately on any staff change with production access.
IP allowlisting
Per-key CIDR allowlists are available on all plans and are the cheapest meaningful control you can add. A request from outside the list returns 403 with code: "ip_not_allowed" and is logged with its source.
PATCH /v1/keys/{id}
{ "allowed_cidrs": ["203.0.113.0/24", "198.51.100.17/32"] }
If a key leaks
- Revoke it first, investigate second.
DELETE /v1/keys/{id}takes effect immediately. - Pull the usage record:
GET /v1/keys/{id}/usagereturns every call made with it, with source IP and endpoint. - Email security@fin-techai.com. We will help you reconstruct what was accessed, and we will not bill for calls made by an attacker.
- Consider whether the identifiers exposed constitute a notifiable incident under your own obligations. They may — see the security page for what a key can reach.