API Keys - Bringin Partner API

Every API call to Bringin requires an api-key header. There are two types:

Key	Purpose	How you get it
Master key	Onboard users, get signup links, check rates	Provided by Bringin during partner setup
Per-user key	Create orders, check balance, manage connections	Returned 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.

Option 1: Via API

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:

User already connected
Existing user, not connected
New user

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.

The user has a Bringin account but hasn’t connected to your application yet. Bringin sends them an email requesting consent.

Response

{
  "status": "pending",
  "userRegistered": true,
  "isUserConnected": false
}

What to show the user: Prompt them to check their email and click the “Confirm connection” link.How you get the key: Once the user confirms, Bringin sends the api-key to your callback URL via the /verification-status webhook. Or you can poll for status.

The user doesn’t have a Bringin account. Bringin sends them an onboarding email and returns a signup URL.

Response

{
  "status": "onboarding",
  "userRegistered": false,
  "isUserConnected": false,
  "signupURL": "https://app.bringin.xyz/signup?inviteId=..."
}

What to show the user: Display the signupURL in your app (button or link) to guide them through Bringin onboarding. The user completes signup + KYC on Bringin.How you get the key: Once KYC is approved, Bringin sends the api-key to your callback URL via the /verification-status webhook. Or you can poll for status.

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

`status`	Meaning	What to do
`onboarding`	Signup or KYC in progress	Keep polling every 15-30 seconds
`pending`	Consent email sent, waiting for user	Keep polling
`connected`	Ready — `apiKey` in response	Store it, stop polling
`rejected`	KYC was rejected	Show 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

Users can find their api-key on the Integrations tab in the Bringin dashboard or mobile app. Click on the partner integration to reveal the API key.

Environment	Dashboard
Sandbox	dev-app.bringin.xyz
Production	app.bringin.xyz

This is useful during development but not recommended for production flows.

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:

Buy connection (EUR to BTC)
Sell connection (BTC to EUR)

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"
}

Request

{
  "email": "user@example.com",
  "callback": "https://yourapp.com/bringin-webhooks",
  "ref": "your-internal-user-id",
  "direction": "CRYPTO_TO_FIAT",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "beneficiaryName": "Alice Smith",
  "currency": "BTC",
  "network": "BTC"
}

Bringin handles onboarding and connection creation. You receive two webhooks:

/verification-status — with the per-user api-key
/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.

​Getting Per-User API Keys

​Option 1: Via API

​Receiving the key via webhook

​Polling for status

​Option 2: From the Bringin dashboard

​Onboarding + Connection in One Call

​Complete Flow Diagram

​Managing API Keys

Getting Per-User API Keys

Option 1: Via API

Receiving the key via webhook

Polling for status

Option 2: From the Bringin dashboard

Onboarding + Connection in One Call

Complete Flow Diagram

Managing API Keys