Skip to main content
Every API call to Bringin requires an api-key header. There are two types:
KeyPurposeHow you get it
Master keyOnboard users, get signup links, check ratesProvided by Bringin during partner setup
Per-user keyCreate orders, check balance, manage connectionsReturned after connecting a user
Per-user keys have limited permissions — they can only push crypto for conversion. They cannot withdraw funds or access sensitive data. Safe to store on client devices (mobile, web) or use from your backend.

​
Getting Per-User API Keys

This is the first step of any integration. Before you can create orders or connections for a user, you need their per-user api-key. Call POST /application/connect with the user’s email. Bringin handles the rest based on whether the user exists. 
POST /api/v0/application/connect
Request
{
  "email": "user@example.com",
  "callback": "https://yourapp.com/bringin-webhooks",
  "ref": "your-internal-user-id"
}
callback is the URL where Bringin sends webhooks with the api-key. If you provide a callback, HMAC signing is required on this request.ref is your internal user ID. It’s returned in all webhooks so you can match them to your users.
Three things can happen depending on the user’s status:
If the user already has an active connection to your application, the api-key is returned immediately in the response. No webhooks, no waiting.
Response
{
  "status": "connected",
  "userRegistered": true,
  "isUserConnected": true,
  "apiKey": "NzY1YWQzZGYwNTE4NDQ4NzkxMTcxMTIxYzVmY2NlMDI="
}
Store the apiKey and start making API calls.
This commonly happens when a user enters their email a second time — for example, they signed up for Bringin, then come back to your app and enter the same email. You get the key right away.

​
Receiving the key via webhook

If you provided a callback URL, Bringin sends a POST request to {callback}/verification-status when the user is ready: 
{
  "userId": "f5cbb00c-d36b-4b0d-b8ef-f412757603df",
  "apikey": "MDU4MTJlNjdkYWU1NGJiZGE0ZjAxNzQ4YzM0NWJlYmE=",
  "verificationStatus": "APPROVED",
  "ref": "your-internal-user-id"
}
Store the apikey — this is the per-user key for all subsequent API calls for this user.
Respond with 200 quickly. You may receive duplicate webhooks — use ref or userId as an idempotency key.

​
Polling for status

If you don’t use webhooks, poll GET /application/connect/status with the user’s email: 
GET /api/v0/application/connect/status?email=user@example.com
statusMeaningWhat to do
onboardingSignup or KYC in progressKeep polling every 15-30 seconds
pendingConsent email sent, waiting for userKeep polling
connectedReady — apiKey in responseStore it, stop polling
rejectedKYC was rejectedShow error to user
Connected response
{
  "status": "connected",
  "apiKey": "ZTY3YzNhMzQ3Yzk4NGJjMmEwZWU1NTQ4NmE5MjJjZTk="
}
Polling uses your master key only. No HMAC signing required.

​
Option 2: From the Bringin dashboard (development only)

Users can find their api-key on the Integration tab in the Bringin dashboard or mobile app. This is useful during development but not recommended for production flows.
EnvironmentDashboard
Sandboxdev-app.bringin.xyz
Productionapp.bringin.xyz
The dashboard also lets users view their EUR balance, transactions, and export statements.

​
Onboarding + Connection in One Call

You can combine user onboarding and connection creation into a single API call by passing direction and the relevant address or bank details:
Request
{
  "email": "user@example.com",
  "callback": "https://yourapp.com/bringin-webhooks",
  "ref": "your-internal-user-id",
  "direction": "FIAT_TO_CRYPTO",
  "btcAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "currency": "BTC",
  "network": "BTC"
}
Bringin handles onboarding and connection creation. You receive two webhooks:
  1. /verification-status — with the per-user api-key
  2. /connection-status — with the deposit IBAN or address
See the Connections guide for details on connection types.

​
Complete Flow Diagram

​
Managing API Keys

  • One key per user per application. Each user connected to your app gets a unique per-user key.
  • Keys don’t expire. Once issued, a per-user key remains valid unless revoked.
  • Lost keys? Call POST /application/connect again with the same email — if the user is already connected, the api-key is returned immediately.
  • Master key rotation — Contact support@bringin.xyz if you need to rotate your master key or secret.