Authentication

BlockBee uses API key authentication. Pass your key as a query parameter or header on every request.

API key types

BlockBee issues two types of keys.

V1 — Receiving payments

• Use: Receiving crypto payments through BlockBee.
• Custody: BlockBee receives funds and forwards them to the wallet you've configured in the dashboard.
• Recovery: Safe to reset; resetting the key does not affect your funds.

V2 — Self-Custodial Wallet

• Use: Receiving payments and sending payouts. Required for the Self-Custodial Wallet and all payout endpoints.
• Custody: You hold your funds directly. BlockBee never touches them.
• Recovery: A separate Recovery Key is generated when you create the V2 key. The Recovery Key is required to regenerate the API key if you lose it.

When to use each

Upgrade to V2 if:

• You need to send payouts (single or bulk).
• You want self-custody of funds — BlockBee never holds them.

Stay on V1 if:

• You only need to receive payments.
• You're fine with BlockBee receiving funds before forwarding them.

For migration steps, see How to upgrade to API Key V2.

Generate a key

Generate keys on the API Keys page in the dashboard.

Pass your key on every request

Either method works. Pick one and stick with it.

Query parameter

Pass your key as the apikey query parameter:

curl "https://api.blockbee.io/btc/create/?apikey=YOUR_API_KEY&callback=https://yoursite.com/webhook"

Header

Pass your key in the apikey header:

curl "https://api.blockbee.io/btc/create/?callback=https://yoursite.com/webhook" \
  -H "apikey: YOUR_API_KEY"

Security

• Never expose your key in client-side code or public repositories. Treat it like a password.
• Always use HTTPS. All BlockBee API endpoints are served over HTTPS.
• Rotate keys periodically to limit exposure if a key is compromised.

If a key is compromised, revoke it from the API Keys page and generate a new one.