Authentication API

Obtain access tokens for authenticating API requests.

Authenticate

Exchange your API credentials for a JWT access token.


POST /business/auth

Request Body

Field	Type	Required	Description
`apiKey`	string	Yes	Your API key
`apiSecret`	string	Yes	Your API secret

Example Request


curl -X POST https://api.test.wakapay.io/business/auth \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret"
  }'


const response = await fetch("https://api.test.wakapay.io/business/auth", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    apiKey: "your_api_key",
    apiSecret: "your_api_secret",
  }),
});
 
const data = await response.json();
console.log(data.accessToken);


import requests
 
response = requests.post(
    'https://api.test.wakapay.io/business/auth',
    json={
        'apiKey': 'your_api_key',
        'apiSecret': 'your_api_secret'
    }
)
 
data = response.json()
print(data['accessToken'])

Success Response

Status Code: 200 OK


{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.****...****",
  "expiresIn": 3600
}

Response Fields

Field	Type	Description
`accessToken`	string	JWT access token to use for authenticated requests
`expiresIn`	number	Token validity duration in seconds (3600 = 1 hour)

Error Responses

400 - Missing Credentials

Missing apiKey or apiSecret fields:


{
  "code": 0,
  "error": "apiKey and apiSecret required"
}

400 - Empty Credentials

Empty apiKey or apiSecret values:


{
  "code": 0,
  "error": "apiKey and apiSecret required"
}

400 - Invalid Payload

Malformed JSON or wrong Content-Type:


{
  "code": 0,
  "error": "invalid payload"
}

Common Causes:

Invalid JSON syntax
Missing Content-Type: application/json header
Sending non-JSON data

401 - Invalid Credentials

Wrong apiKey or apiSecret:


{
  "code": 0,
  "error": "invalid credentials"
}

Using the Access Token

Include the access token in the Authorization header of all subsequent API requests:


Authorization: Bearer {accessToken}

Example


curl https://api.test.wakapay.io/business/balance?currency=USD \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Best Practices

Caching Tokens

Cache tokens in memory and reuse them until they expire to avoid unnecessary authentication requests:


class TokenManager {
  constructor(apiKey, apiSecret) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.token = null;
    this.expiresAt = null;
  }
 
  async getToken() {
    // Return cached token if still valid (with 60s buffer)
    if (this.token && Date.now() < this.expiresAt - 60000) {
      return this.token;
    }
 
    // Request new token
    const response = await fetch("https://api.test.wakapay.io/business/auth", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        apiKey: this.apiKey,
        apiSecret: this.apiSecret,
      }),
    });
 
    const data = await response.json();
 
    if (data.error) {
      throw new Error(data.error);
    }
 
    this.token = data.accessToken;
    this.expiresAt = Date.now() + data.expiresIn * 1000;
 
    return this.token;
  }
 
  clearToken() {
    this.token = null;
    this.expiresAt = null;
  }
}

Handling Token Expiration

When you receive a 401 Unauthorized error, clear your cached token and request a new one:


async function makeAuthenticatedRequest(url, options) {
  let token = await tokenManager.getToken();
 
  try {
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${token}`,
      },
    });
 
    // Token expired, get new token and retry once
    if (response.status === 401) {
      tokenManager.clearToken();
      token = await tokenManager.getToken();
 
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          Authorization: `Bearer ${token}`,
        },
      });
    }
 
    return response;
  } catch (error) {
    throw error;
  }
}

Security Best Practices

Never log tokens: Tokens are sensitive and should never be logged or exposed
Use HTTPS: Always use HTTPS endpoints to prevent token interception
Store securely: Never commit API keys/secrets to version control
Environment variables: Store credentials in environment variables
Separate environments: Use different keys for test and production

Token Expiry

Duration: Tokens expire after 3600 seconds (1 hour)
Refresh: Request a new token before the current one expires
Buffer: Implement a 60-second buffer before expiry to prevent edge cases

Authentication Guide - Detailed authentication guide with best practices
Error Handling - Learn about error codes and handling