Zaira Auth
All requests require the x-api-key header for authentication (except /health).
API key
Include your API key in every request:
x-api-key: your-api-key
Contact the Zaira team to receive your API key.
User identity
After authentication, most endpoints require user identification. Use the user_uuid returned from /initiate:
x-user-uuid: <user-uuid>
Connecting a user at /initiate
/initiate/initiate is where you tell Zaira who it is talking to. Every call needs both x-api-key and x-bakkt-api-key; what you add alongside them decides which kind of user you get.
| Scenario | Headers | What Zaira does |
|---|---|---|
| New user | x-api-keyx-bakkt-api-key | Registers a brand-new user that onboards through Zaira from scratch. |
| Existing Bakkt user, custodial wallet | x-api-keyx-bakkt-api-keyx-bakkt-custodial-wallet-uuid | Signs in with the wallet, resolves the Bakkt user, and links the wallet to the Zaira user. |
| Existing Bakkt user, self-custody | x-api-keyx-bakkt-api-keyx-bakkt-session-id | Resolves the Bakkt user from the session and acts through that session. |
In all three cases the response is the same: the Zaira user_uuid.
Why two different credentials
Zaira needs a way to act on the user's behalf, and there are exactly two:
x-bakkt-custodial-wallet-uuid— the wallet is held by Bakkt, so Zaira can sign with it. Signing in with the wallet is itself the proof that you are entitled to it. This is the stronger capability: these users can execute transfers.x-bakkt-session-id— the user holds their own wallet, so Zaira cannot sign for them. Instead it acts through the user's own Bakkt session. These users can manage beneficiaries and retrieve payout details, but Zaira will not execute transfers for them.
If you supply both, the custodial wallet takes precedence.
Rules
x-bakkt-api-keyis always required, including for brand-new users.- To connect an existing Bakkt user, add either
x-bakkt-custodial-wallet-uuidorx-bakkt-session-id. Omit both to register a new user. - You do not send the Bakkt user UUID. Zaira retrieves the user's Bakkt identity directly from Bakkt using the wallet or session you supplied.
- If a user holds a custodial wallet, send
x-bakkt-custodial-wallet-uuid. It is what enables Zaira to execute transfers for them; connecting them with a session ID alone sets them up as a self-custody user instead.
Optional ip_address
ip_addressPOST /initiate accepts an optional JSON body. The only supported field is ip_address, the user's client IP (IPv4 or IPv6):
{
"ip_address": "203.0.113.1"
}
Self-custody wallet funding requires a stored IP
ip_addressis not required to initiate a user. Omit it and initiation still succeeds; balances, history, fees, beneficiaries, and other supported self-custody capabilities remain available.Wallet funding does not. For a US self-custody user with no stored IP, Zaira will not start a funding journey (linking a bank account or pulling funds into the wallet). This is separate from sending a transfer to a beneficiary: self-custody users still never have Zaira execute that transfer — they sign and send it themselves. Missing IP only turns funding off.
If a US self-custody user asks to fund their wallet and no IP is stored, Zaira returns this fixed message instead of calling any funding tools:
Wallet funding isn't available for your account right now. Please contact your app provider for help.
Store the IP on /initiate. Sending it only on /ask or /ask/stream does not persist it and does not enable funding.
Calling /initiate again for an existing user can change the stored IP without changing the user's identity or custody type:
| Body | Effect |
|---|---|
{ "ip_address": "203.0.113.1" } | Set or overwrite the stored IP. |
{ "ip_address": null } | Clear the stored IP. Funding becomes unavailable for self-custody users. |
{} or no body | Leave any stored IP unchanged. |
Omitting the field never clears an existing IP. If the field is present, it must be a non-empty IP string or null.
Failure cases
| Status | Cause |
|---|---|
400 | x-bakkt-api-key is missing. |
400 | x-bakkt-custodial-wallet-uuid is not a valid UUID. |
400 | The custodial wallet does not exist. |
400 | The Bakkt user belongs to a different Zaira merchant. |
400 | ip_address is present but is not a non-empty string and is not null. |
401 | x-api-key is missing or invalid. |
401 | Not entitled to the supplied custodial wallet. |
401 | The Bakkt user could not be resolved from the supplied session. |
409 | The custodial wallet is already linked to a different user. |
On any of these, no user is created and no wallet is linked.
Sending messages as a Bakkt user
/initiate connects the user once. Messaging endpoints (/ask, /ask/stream) authenticate the user on every request, so Bakkt credentials must be sent each time — not just at initiation.
As at /initiate, x-bakkt-api-key is required from every caller, including users who onboarded through Zaira from scratch. A request without it is rejected with 400 and Missing "x-bakkt-api-key" header.
| User type | Headers on every /ask request |
|---|---|
| Custodial | x-api-key + x-user-uuid + x-bakkt-api-key |
| Self-custody | x-api-key + x-bakkt-api-key + x-bakkt-session-id |
Self-custody users must supply x-bakkt-session-id on every request. Because that session already identifies the user, x-user-uuid is optional for them — Zaira resolves the user from the session rather than from the UUID. You may still send it, which keeps the request shape consistent across user types.
For everyone else x-user-uuid is required: with no session to resolve the user from, it is the only identifier Zaira has.
Zaira has no wallet to sign with for self-custody users, so without a live session it has no way to act on their behalf and the request fails:
{
"error": true,
"message": "Unauthorized: self-custody user must authenticate through Bakkt Session ID",
"errorCode": 401
}Custodial users do not send a session ID. Zaira signs in with the wallet stored at /initiate and establishes the session itself.
What each user type can do
Custody determines which operations Zaira can carry out. This is resolved internally and is not exposed in any response.
| Capability | Custodial | Self-custody |
|---|---|---|
| Balances, transaction history | Yes | Yes |
| Exchange rates, fees | Yes | Yes |
| Wallet funding | Yes | Yes, only if ip_address was stored at /initiate |
| Create and manage beneficiaries | Yes | Yes |
| Execute a transfer | Yes | No — Zaira prepares the beneficiary and payout details, the user signs and sends it themselves |
Wallet funding means adding money to the wallet (for example linking a bank account or starting an ACH pull). It is not the same as executing a transfer to a beneficiary.
Endpoint requirements
| Endpoint | API key | User identity | Bakkt API key |
|---|---|---|---|
POST /initiate | Required | Not required | Required |
POST /ask | Required | Required, unless x-bakkt-session-id is sent | Required |
POST /ask/stream | Required | Required, unless x-bakkt-session-id is sent | Required |
POST /check-execution | Required | Required | Not required |
GET /sessions | Required | Required | Not required |
GET /info | Required | Not required | Not required |
/webhooks | Required | Not required | Not required |
GET /health | Not required | Not required | Not required |
The /initiate endpoint returns a user_uuid that you must use for all subsequent requests.
Updated 13 days ago
