Authentication

Send your API key as a bearer token in the Authorization header of every request:

POST /v1/decide HTTP/1.1
Host: api.finic.ai
Authorization: Bearer gsk_…
Content-Type: application/json

Keys start with gsk_. A request without a valid key fails with 401 authentication_error.

Create a keyCopy Anchor Link

Create keys in the portal at portal.finic.ai/keys. The full key is shown once, when you create it; the portal can't show it again. If you lose a key, create a new one and revoke the old one.

Keys belong to your organization. The portal's usage metrics are broken down by key, so a separate key for each service and environment (for example, production and staging) tells you where requests come from and lets you revoke one without affecting the others.

Store keys safelyCopy Anchor Link

• Keep keys on your servers, in environment variables or a secrets manager.
• Never put a key in browser code, a mobile app or source control. Anyone who has the key can make requests as your organization.
• Don't log the Authorization header.

Rotate and revokeCopy Anchor Link

Revoke a key at portal.finic.ai/keys. Requests that use a revoked key fail with 401 authentication_error.

To rotate a key without downtime:

1. Create a new key.
2. Deploy it everywhere the old key is used.
3. Confirm in the portal's usage metrics that the old key has stopped receiving requests.
4. Revoke the old key.

Authentication errorsCopy Anchor Link

{
  "error": {
    "type": "authentication_error",
    "message": "…",
    "param": null
  }
}

See Errors for every error type.