Authentication

BlendFi uses simple Bearer-token authentication. Every /v1/* request carries your API key in the Authorization header. There's no login, no session, no token refresh, the key is the session.

The contract

GET /v1/users HTTP/1.1
Host: api.sandbox.blendfi.com.br
Authorization: Bearer sk_test_xxx

Three rules:

1. Bearer prefix required. Just Authorization: sk_test_… returns 401 authentication_required. Mind the space.
2. Key sent on every request. No exchange-for-session-cookie pattern. The key is plaintext on every wire, that's why TLS is required.
3. HTTPS only. Plain HTTP is rejected at the edge.

Key formats

Cross-environment use is rejected:

• sk_test_… against the production base URL → 401 api_key_env_mismatch
• sk_live_… against the sandbox base URL → 401 api_key_env_mismatch

This is intentional: prevents accidentally moving real money during testing, and prevents test calls from polluting production.

Key rotation

Production-grade integrations rotate keys on a schedule (every 90 days is a common cadence) or in response to compromise.

Rotation is self-serve via the API. A single call, POST /v1/api-keys/{id}/rotate, issues a new key with the same capabilities and name, returns the new secret exactly once, and immediately revokes the old key. The recommended flow:

1. GET /v1/api-keys to find the id of the key you want to rotate.
2. POST /v1/api-keys/{id}/rotate; capture the new secret from the response (it is shown only once and cannot be retrieved later).
3. Roll the new secret out to your application (deploy or hot-reload the secret).

Rotation is an immediate cutover: the old key stops authenticating the instant you rotate, so requests still using it return authentication_failed. Have the new secret ready to deploy as part of the same change so there is no gap.

Errors

Full descriptions in the errors catalog.

Read next

• Sandbox & keys, environments and the key-request flow
• Concepts → Errors and retries, error response shape
• Quickstart, make your first call