Skip to main content
Before integrating with the Blaaiz Platform API, review the following guidelines to ensure a smooth and reliable development experience.

​
Using the Blaaiz Platform API

​
Authentication

  • All external API requests must be authenticated using a valid Bearer access token.
  • Generate OAuth credentials from the Blaaiz Dashboard after API Services have been enabled for your account.
  • Exchange those credentials at /oauth/token using grant_type=client_credentials.
  • Request the token with the scopes assigned to your credentials (e.g. wallet:read payout:create). See Authentication — Scopes.
  • Include Authorization: Bearer <access_token> in every external API request.
  • Keep your OAuth client_secret secure and never expose it in client-side code or public repositories.
  • Development and production use different OAuth credentials. Always use the credentials from the same environment as the base URL you are calling.
  • If you cannot see the API & Webhooks page in the dashboard, your account has not been provisioned for API Services yet. See Authentication and Getting Started.
  • Legacy API key creation is disabled. If you still use a legacy API key integration with x-blaaiz-api-key, migrate to OAuth immediately.

​
Customer update rules

  • Only NON-VERIFIED customer details can be fully updated.
  • If a customer is VERIFIED, only fields that are currently null can be updated.
  • The customer’s country must match the identity document provided for KYC.

​
TIN and identification labels

  • If you need to collect a tin, do not hardcode the label shown to your users.
  • Get the correct label or field from the Get identification type endpoint.

​
Collection method note

  • For the API collection endpoint, the currently documented method is card.
  • Open Banking should not be treated as a supported collection method in the public docs.

​
Rate Limits & Usage

  • To ensure fair usage and maintain platform stability, the Blaaiz API enforces rate and usage limits.
  • Requests exceeding these limits may be throttled or temporarily blocked.
  • If you anticipate high request volumes, contact Blaaiz support@blaaiz.com to discuss your use case.

​
Response Format

  • All API responses are returned in JSON format.
  • Successful responses include the requested data.
  • Error responses include a descriptive message field to help you understand and resolve the issue.
Example error response: 
{
  "message": "Invalid or missing access token"
}

​
Best Practices

  • Handle errors gracefully by checking HTTP status codes and error messages.
  • Log API responses during development to aid debugging.
  • Always test integrations in a safe environment before going live.