Quickstart

From "I just got an API key" to "I made a real authenticated call" in about five minutes.

The five-minute path. By the end, you've authenticated against BlendFi and created your first test user.

1. Set your environment

Don't have a sandbox key yet?

Keys are issued after a short meeting with the BlendFi team. Book a meeting and you walk out with your key. Full flow in Sandbox and keys.

Drop your sandbox key into a shell variable so the rest of the examples are copy-paste friendly.

export BLENDFI_KEY=sk_test_replace_with_your_real_key
export BLENDFI_BASE=https://api.sandbox.blendfi.com.br

You can tell which environment a key targets by its prefix:

Prefix	Environment	What it can do
`sk_test_…`	Sandbox	Anything. No real money moves.
`sk_live_…`	Production	Real money. Issued during the production handoff meeting.

Sandbox keys cannot accidentally hit production, and vice versa, both are rejected with 401 authentication_failed. See Authentication for the full contract.

2. Authenticate every request

Every call to /v1/* carries your key in the Authorization header as a Bearer token:

Authorization: Bearer sk_test_…

Three things to know:

The word Bearer is required. Just Authorization: sk_test_… returns 401 authentication_required.
The key is sent on every request. No login, no session cookie, no token refresh. The key is the session.
Capabilities are per-key. A key has scoped capabilities (e.g., users:create, transactions:create). If a key tries an endpoint it isn't scoped for, you get 403 missing_capability.

3. Make your first call

Create a test user. This is the canonical "first call" because most other endpoints need a user ID.

curl -X POST $BLENDFI_BASE/v1/users \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "external_id": "your-internal-user-id-001",
    "name": "Ada Lovelace",
    "document_type": "cpf",
    "document_number": "52998224725"
  }'

import crypto from "node:crypto";

const res = await fetch(`${process.env.BLENDFI_BASE}/v1/users`, {
  method: "POST",
  headers: {
    "authorization": `Bearer ${process.env.BLENDFI_KEY}`,
    "idempotency-key": crypto.randomUUID(),
    "content-type": "application/json",
  },
  body: JSON.stringify({
    external_id: "your-internal-user-id-001",
    name: "Ada Lovelace",
    document_type: "cpf",
    document_number: "52998224725",
  }),
});
console.log(await res.json());

import os, uuid, requests

res = requests.post(
    f"{os.environ['BLENDFI_BASE']}/v1/users",
    headers={
        "authorization": f"Bearer {os.environ['BLENDFI_KEY']}",
        "idempotency-key": str(uuid.uuid4()),
        "content-type": "application/json",
    },
    json={
        "external_id": "your-internal-user-id-001",
        "name": "Ada Lovelace",
        "document_type": "cpf",
        "document_number": "52998224725",
    },
)
print(res.json())

If everything's wired up:

{
  "id": "usr_01J…",
  "external_id": "your-internal-user-id-001",
  "name": "Ada Lovelace",
  "document_type": "cpf",
  "document_masked": "***.224.725-**",
  "kyc_status": "not_started",
  "created_at": "2026-04-29T13:00:00Z"
}

That's it. You're authenticated.

CPF format

Use 11 digits, no dots or dashes. The example above (52998224725) is a valid test CPF you can reuse in sandbox. Real CPFs in sandbox get encrypted just like in production, never paste real personal data into the docs.

What `Idempotency-Key` does

Short version: it's a unique string (we recommend a UUID) that makes the request safe to retry. If your network drops mid-call and you retry with the same key, you get the same response back instead of a duplicate user. Every POST and PATCH in BlendFi requires it, see Idempotency.

When something goes wrong

Every error response has the same response shape:

{
  "code": "authentication_required",
  "message": "Authorization header missing.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG"
}

Branch on code (stable). The two errors you'll see most often while getting started:

Code	Why	Fix
`401 authentication_required`	Header missing or doesn't start with `Bearer`	Add the header; mind the space after `Bearer`
`401 authentication_failed`	Key unknown, revoked, or pasted with a typo	Re-copy from your onboarding email
`403 missing_capability`	Key valid but not scoped for this endpoint	Email us; we'll widen the capabilities

The full alphabetical catalog is in the errors catalog.

1. Set your environment

2. Authenticate every request

3. Make your first call

What `Idempotency-Key` does

When something goes wrong

What to read next

On this page

Quickstart

1. Set your environment

2. Authenticate every request

3. Make your first call

What Idempotency-Key does

When something goes wrong

What to read next

On this page

What `Idempotency-Key` does