> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business.blaaiz.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Learn how to authenticate your API requests to the Blaaiz API.
## 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](https://business-dev.blaaiz.com)
* Production: [business.blaaiz.com](https://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](/guides/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. You **must** include the `scope` parameter with the individual scopes your token needs:
```bash theme={null}
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.
**Do not pass bundle names** (e.g. `full-access`, `read-only`) in the `scope`
parameter when requesting a token. Bundles are a shortcut for credential
creation only — they are expanded into individual scopes at that time. When
minting a token, you must list the individual scopes. Passing a bundle name
will result in an `Invalid scope(s) provided` error.
**Do not omit the `scope` parameter.** If you omit it, the token will not
inherit your credential's scopes and your API requests will fail with
`403 Access Denied`.
If your credentials were created with the `full-access` bundle, pass all
individual scopes as shown below:
```
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 payout:create swap:create transaction:read fees:read rates:read file:upload webhook:read webhook:write webhook:replay mock:webhook:trigger
```
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](#individual-scopes).
| Bundle | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| `full-access` | All available scopes (default if none specified) |
| `read-only` | Read access to wallets, currencies, customers, transactions, fees, rates, and webhooks |
| `collections` | Create collections, manage customers, and read transactions |
| `payouts` | Create payouts, read wallets, banks, beneficiaries, fees, and rates |
| `virtual-accounts` | Create and manage virtual accounts and customers |
| `customers` | Manage customers, beneficiaries, and file uploads |
### Individual scopes
You can also select scopes individually for fine-grained control:
| Scope | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wallet:read` | Read business wallets |
| `currency:read` | Read supported currencies |
| `bank:read` | Read bank and bank account lookup data |
| `customer:read` | Read customers |
| `customer:write` | Create, update, and upload customer KYC/KYB data — covers identity files for individuals, beneficial-owner edits and KYB document registration for businesses, and `/submit` |
| `beneficiary:read` | Read customer beneficiaries |
| `virtual-account:read` | Read virtual accounts and identification types |
| `virtual-account:create` | Create virtual accounts |
| `virtual-account:close` | Close virtual accounts |
| `collection:create` | Initiate fiat collections and attach customers |
| `collection:crypto:create` | Read crypto networks and initiate crypto collections |
| `collection:interac:accept` | Accept Interac money requests |
| `collection:interac:create` | Initiate Interac money requests |
| `payout:create` | Initiate payouts |
| `swap:create` | Initiate swaps |
| `transaction:read` | Read business transactions |
| `fees:read` | Read fee breakdowns |
| `rates:read` | Read exchange rates |
| `file:upload` | Generate presigned file upload URLs |
| `webhook:read` | Read webhook configuration |
| `webhook:write` | Create and update webhook configuration |
| `webhook:replay` | Replay webhook deliveries |
| `mock:webhook:trigger` | Trigger mock webhook simulations |
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](#getting-an-access-token).
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:
```bash theme={null}
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:
```bash theme={null}
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 `.
### 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.