Skip to main content

Authentication

How you authenticate depends on your integration option:

OptionHow requests are made
BlockFinaX walletsEach customer signs in (email, Google or passkey) and your app calls the API with that customer's session token
Your own walletsYour server calls the API with your partner credentials, issued during partner onboarding, and signs transactions with your own keys

The rest of this page covers customer session tokens.

Read endpoints for markets, pools, rates and settlement data are public. Endpoints that act for a user, or read a user's own data, need a session token.

Get a session token by email​

Step 1: request a code​

curl -X POST $BFX/api/wallet/auth/email/start \
  -H "Content-Type: application/json" \
  -d '{ "email": "treasury@example.com" }'
{ "requestId": "..." }

Step 2: verify the code​

curl -X POST $BFX/api/wallet/auth/email/verify \
  -H "Content-Type: application/json" \
  -d '{ "email": "treasury@example.com", "requestId": "...", "code": "123456" }'
{ "sessionToken": "..." }

Codes expire after 5 minutes and allow 5 attempts. A new code can be requested every 60 seconds. Sessions last up to 12 hours.

Use the token​

Send it on every authenticated request, either way:

Authorization: Bearer <sessionToken>
X-Session-Token: <sessionToken>

Passkey sign-in​

Users who already have a passkey can sign in with WebAuthn:

  1. POST /api/wallet/passkey/signin/options returns a WebAuthn challenge.
  2. The browser runs navigator.credentials.get with it.
  3. POST /api/wallet/passkey/signin/verify with the assertion returns { sessionToken }.

The session is not a signing key​

A session token lets you read the user's data and prepare transactions for them. It cannot move funds: every transaction still needs the user's passkey signature. Treat the token as a secret all the same, because it reveals the user's positions and balances.

Accounts​

curl $BFX/api/v2/accounts -H "Authorization: Bearer $TOKEN"

Returns the user's chain accounts, including the Stellar smart-wallet contract address that buys protection and holds liquidity.

Acting for a business account​

A user who belongs to a business account can act for it. Add its id to protocol requests:

curl $BFX/api/v2/balances \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-BFX-Organisation: 42"

The API checks on every request that the user is an active member, then uses the business account for balances, positions, quotes and prepared transactions. The member's role decides what the relayer will send: admins anything, operators pool calls only, viewers nothing. List a user's business accounts with GET /api/organisations. See Accounts endpoints.