Authentication

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:
   • Development: business-dev.blaaiz.com
   • Production: business.blaaiz.com
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.

Getting an access token

Exchange your OAuth credentials for a short-lived access token. You must include the scope parameter with the individual scopes your token needs:

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 individual 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.

scope=wallet:read currency:read bank:read customer:read customer:write beneficiary:read virtual-account:read virtual-account:create virtual-account:close collection:create collection:crypto:create collection:interac:accept collection:interac:create interac-auto-deposit-email:create interac-auto-deposit-email:read payout:create swap:create transaction:read fees:read rates:read file:upload webhook:read webhook:write webhook:replay mock:webhook:trigger crypto-wallet:read crypto-wallet:create crypto-asset:read crypto-transaction:read crypto-payout:create crypto-swap:create

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 (credential creation only)

For convenience, Blaaiz provides pre-built bundles that group related scopes. Bundles can only be used when creating or rotating credentials from the dashboard. They are expanded into individual scopes at that time. When requesting a token from /oauth/token, you must use individual scopes.

The full-access and collections bundles include both interac-auto-deposit-email scopes. The read-only bundle includes only interac-auto-deposit-email:read.

Individual scopes

You can also select scopes individually for fine-grained control:

If you do not specify any scopes or bundle when creating credentials, the full-access bundle is assigned by default. This means your credentials will have all individual scopes available. You still need to pass those individual scopes in the scope parameter when requesting a token.

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

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.

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.