Authentication

Overview

The Zuba API uses OAuth 2.0 Client Credentials flow for secure M2M (machine-to-machine) authentication. You’ll exchange your Client ID and Client Secret for a short-lived JWT access token, which you’ll use to authenticate API requests.

Getting Your API Credentials

Step 1: Generate Credentials

Log in to your Zuba Dashboard (use dash-test.zuba.com for test environment)
Navigate to API Settings
Click Generate API Key or Create API Credentials
Important: Copy and save your credentials immediately - you won’t be able to see the Client Secret again!

You’ll receive the following credentials:

Client ID: Your application’s public identifier (e.g., ao6CMrtuM0pdUtAbcYRr5nlJCma90B2S)
Client Secret: Your application’s secret key (e.g., aS-abvckfP2ZoDh9...)
Token URL: Auth0 endpoint to exchange credentials for tokens (e.g., https://zuba-test.us.auth0.com/oauth/token)
Audience: API identifier (typically https://api.zuba.com)

Keep your Client Secret secure! Never share it publicly or commit it to version control. Treat it like a password. If compromised, immediately rotate your credentials in the dashboard.

Authentication Flow

Step 2: Request an Access Token

Exchange your Client ID and Client Secret for a JWT access token:

curl -X POST "https://zuba-test.us.auth0.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.zuba.com",
    "grant_type": "client_credentials"
  }'

Successful Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 86400
}

The access_token is a JWT that’s valid for 24 hours (86400 seconds). You’ll need to request a new token when it expires.

Step 3: Use the Access Token

Include the access token in the Authorization header of every API request:

curl -X GET "https://api-test.zuba.com/v1/payouts" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6..." \
  -H "Content-Type: application/json"

Token Management

Token Expiration

Access tokens expire after 24 hours. Implement token caching and refresh logic to avoid requesting a new token for every API call:

Example: Token Cache

let cachedToken = null;
let tokenExpiry = null;

async function getValidToken() {
  const now = Date.now();

  // Return cached token if still valid (with 5-minute buffer)
  if (cachedToken && tokenExpiry && now < tokenExpiry - 300000) {
    return cachedToken;
  }

  // Request new token
  const response = await fetch('https://zuba-test.us.auth0.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.ZUBA_CLIENT_ID,
      client_secret: process.env.ZUBA_CLIENT_SECRET,
      audience: 'https://api.zuba.com',
      grant_type: 'client_credentials'
    })
  });

  const data = await response.json();

  // Cache token and expiry time
  cachedToken = data.access_token;
  tokenExpiry = now + (data.expires_in * 1000);

  return cachedToken;
}

Environments

Zuba provides separate environments for development and production:

Environment	Dashboard	Token URL	API Base URL
Test	https://dash-test.zuba.com	https://zuba-test.us.auth0.com/oauth/token	https://api-test.zuba.com
Production	https://dash.zuba.com	https://zuba.us.auth0.com/oauth/token	https://api.zuba.com

Always test with the Test environment before moving to production. Use separate credentials for each environment.

Authentication Errors

Token Request Errors

Error	Cause	Solution
`access_denied` / `Unauthorized`	Invalid Client ID or Client Secret	Verify credentials are correct and not expired
`invalid_grant`	Invalid grant_type	Ensure grant_type is “client_credentials”
`invalid_audience`	Wrong audience value	Use the correct audience for your environment

API Request Errors

HTTP Status	Error	Cause	Solution
`401`	Unauthorized	Missing, invalid, or expired token	Request a new access token and retry
`403`	Forbidden	Token lacks required permissions	Contact support to verify account permissions

Example error response:

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Security Best Practices

Environment Variables

Never hardcode credentials in your application code. Use environment variables:

.env

ZUBA_CLIENT_ID=ao6CMrtuM0pdUtAbcYRr5nlJCma90B2S
ZUBA_CLIENT_SECRET=aS-abvckfP2ZoDh9100SS2ix_CigMC27Kc4y18iMIRVBxKlMPopL5kQr_bGY56hE
ZUBA_TOKEN_URL=https://zuba-test.us.auth0.com/oauth/token
ZUBA_API_BASE_URL=https://api-test.zuba.com

const clientId = process.env.ZUBA_CLIENT_ID;
const clientSecret = process.env.ZUBA_CLIENT_SECRET;

HTTPS Only

Always use HTTPS for both token requests and API calls. Never send credentials or tokens over HTTP.

Credential Rotation

Regularly rotate your credentials:

Generate new credentials in the dashboard
Update your environment variables
Deploy the changes
Delete the old credentials in the dashboard

Token Storage

Store tokens in memory, not in databases or files
Never log tokens in application logs
Clear tokens when they expire
For serverless environments, request a new token for each execution (they’re cached by Auth0)

Least Privilege

Request only the permissions your application needs. Contact support to configure specific scopes for your credentials.

Testing Authentication

Test your authentication setup before making actual API calls:

# Step 1: Get access token
TOKEN=$(curl -s -X POST "https://zuba-test.us.auth0.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.zuba.com",
    "grant_type": "client_credentials"
  }' | jq -r '.access_token')

# Step 2: Test API request
curl -X GET "https://api-test.zuba.com/ledger/balances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

A successful authentication test will return your account balances or an empty array if no balances exist yet.

Authentication

Overview

Getting Your API Credentials

Step 1: Generate Credentials

Authentication Flow

Step 2: Request an Access Token

Step 3: Use the Access Token

Token Management

Token Expiration

Environments

Authentication Errors

Token Request Errors

API Request Errors

Security Best Practices

Testing Authentication

Next Steps

Quickstart Guide

API Reference

Documentation Index

​Overview

​Getting Your API Credentials

​Step 1: Generate Credentials

​Authentication Flow

​Step 2: Request an Access Token

​Step 3: Use the Access Token

​Token Management

​Token Expiration

​Environments

​Authentication Errors

​Token Request Errors

​API Request Errors

​Security Best Practices

​Testing Authentication

​Next Steps

Quickstart Guide

API Reference

Overview

Getting Your API Credentials

Step 1: Generate Credentials

Authentication Flow

Step 2: Request an Access Token

Step 3: Use the Access Token

Token Management

Token Expiration

Environments

Authentication Errors

Token Request Errors

API Request Errors

Security Best Practices

Testing Authentication

Next Steps