Skip to main content

​
Overview

The Blaaiz Platform API uses OAuth 2.0 client credentials for external API access. After API Services are enabled for your account, generate your OAuth credentials from the Blaaiz Dashboard, exchange them for a short-lived access token, and send that token as a Bearer token on every API request. For older integrations, Blaaiz may still accept the legacy x-blaaiz-api-key header temporarily. That path is deprecated. New integrations should use OAuth only, and existing integrations should switch as soon as possible.

​
Accessing your OAuth credentials

  1. Sign in to the correct dashboard for your environment:
  2. Open API & Webhooks from the dashboard menu.
  3. Create your OAuth credentials from that page if none exist yet.
  4. Copy the displayed client_id and client_secret and store them securely.
If the API & Webhooks page is missing, your account has not yet been provisioned for API Services. See Getting Started for the access steps.
The client_secret is a confidential credential. Do not expose it in client-side code or public repositories. If it is lost or compromised, rotate it from the dashboard and update your integration immediately.
Your client_secret should be treated as a one-time-visible secret. Store it securely when it is shown. If you lose it later, rotate the OAuth credentials from API & Webhooks and update your integration.

​
Getting an access token

Exchange your OAuth credentials for a short-lived access token. Use the scopes that were assigned when you created your credentials: 
curl -X POST https://api-prod.blaaiz.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=wallet:read payout:create transaction:read"
The scope parameter must be a space-separated list of scopes that were assigned to your credentials. You can request all of them or a subset. The credential creation response includes the full list of available scopes in the scopes field. The access token returned from /oauth/token is short-lived. Request a new one when it expires. Client credentials tokens do not use refresh tokens. When the current token expires, request a new access token from /oauth/token.

​
Scopes

When creating OAuth credentials, you can choose which API capabilities to grant. Scopes control what your access token is allowed to do.

​
Scope bundles

For convenience, Blaaiz provides pre-built bundles that group related scopes:
BundleDescription
full-accessAll available scopes (default if none specified)
read-onlyRead access to wallets, currencies, customers, transactions, fees, and webhooks
collectionsCreate collections, manage customers, and read transactions
payoutsCreate payouts, read wallets, banks, beneficiaries, and fees
virtual-accountsCreate and manage virtual accounts and customers
customersManage customers, beneficiaries, and file uploads

​
Individual scopes

You can also select scopes individually for fine-grained control:
ScopeDescription
wallet:readRead business wallets
currency:readRead supported currencies
bank:readRead bank and bank account lookup data
customer:readRead customers
customer:writeCreate, update, and upload customer KYC data
beneficiary:readRead customer beneficiaries
virtual-account:readRead virtual accounts and identification types
virtual-account:createCreate virtual accounts
virtual-account:closeClose virtual accounts
collection:createInitiate fiat collections and attach customers
collection:crypto:createRead crypto networks and initiate crypto collections
collection:interac:acceptAccept Interac money requests
payout:createInitiate payouts
swap:createInitiate swaps
transaction:readRead business transactions
fees:readRead fee breakdowns
file:uploadGenerate presigned file upload URLs
webhook:readRead webhook configuration
webhook:writeCreate and update webhook configuration
webhook:replayReplay webhook deliveries
mock:webhook:triggerTrigger mock webhook simulations
If you do not specify any scopes or bundle when creating credentials, full-access is assigned by default.
Scopes are set when credentials are created or rotated. To change scopes, rotate your credentials and specify the new scope set.

​
Rotating credentials

If your client_secret is compromised, or you need to change scopes, rotate your credentials from the dashboard:
  1. Go to API & Webhooks in your Blaaiz Dashboard.
  2. Click Rotate on your existing OAuth credentials.
  3. Optionally select a new scope bundle or individual scopes.
  4. Copy the new client_secret immediately — it is only shown once.
  5. Update your integration to use the new credentials.
Rotation immediately revokes the previous client_secret and all access tokens issued from it. Your integration will need to request a new token using the new credentials.

​
Using the access token

Include the access token in the Authorization header of every external API request: 
curl -X GET https://api-prod.blaaiz.com/api/external/wallet \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Legacy API keys

Creation of new legacy API keys is disabled. Legacy API key authentication will be fully removed soon. Migrate to OAuth as soon as possible.
If you still have an older API-key-based integration, plan the switch to client credentials as urgent work. Legacy requests use the API key header instead of a Bearer token: 
curl -X GET https://api-prod.blaaiz.com/api/external/wallet \
  -H "x-blaaiz-api-key: YOUR_LEGACY_API_KEY"
Use this only to maintain an older integration while you complete the move to OAuth.

​
Important notes

  • Every external API request must use a valid Bearer access token.
  • Development and production use different dashboard accounts and different OAuth credentials.
  • Use the same environment for your dashboard, token request, and API base URL.
  • Keep your client_secret server-side only.

​
Authentication errors

Blaaiz Platform API provides specific error messages for authentication issues:

​
401 Unauthorized

  • The Bearer token is missing.
  • The Bearer token is expired, malformed, or invalid.
Ensure that you first exchanged your credentials at /oauth/token, then send the access token as Authorization: Bearer <token>.

​
403 Access Denied

This error occurs in the following cases:
  • Your business no longer has access to API Services.
  • Your request scope is insufficient for the endpoint being called.
  • Your request is blocked by another policy such as IP whitelisting in production.
Make sure your account is provisioned for API Services, your production IPs are whitelisted, and your integration has switched fully to OAuth.