Skip to main content

Overview

To interact with the Onboard Connect API, 3rd party clients must authenticate using one of the following methods:
  • Session-based authentication (x-auth-token) - Used for requests requiring an authenticated user session.
  • API Key authentication (x-api-key) - Used to identify your 3rd party application.
  • HMAC Signature authentication - Required for more sensitive endpoints (e.g., user creation), ensuring request integrity.
Check the specific endpoint documentation to determine which authentication method is required.

Authentication methods

Used for endpoints requiring an authenticated user session.Steps: Obtain an x-auth-token after completing user authentication (e.g., OTP login).Include this token in the request headers:
Authorization: Bearer <x-auth-token>
Example Request:
GET /users/me
Authorization: Bearer <x-auth-token>
Some endpoints require your API key to identify your application as the requesting 3rd party client.Steps:
  1. Retrieve your API key from the Business Dashboard after onboarding.
  2. Include the API key in either:
x-api-key: <your-api-key>
Some endpoints require x-api-key while others do not. Check the endpoint’s documentation to confirm.
Certain sensitive endpoints, such as user creation, require an HMAC SHA-256 signature for verification. Requests without a valid signature will be rejected.

Required Headers:

HeaderDescription
x-api-keyFound in the Business Dashboard
x-signatureHMAC-SHA256 signature of the request body
x-timestampUnix timestamp (seconds) when the signature was generated

How to generate x-signature

The signature is generated using HMAC SHA-256 with your API secret as the key.Example (JavaScript):
const crypto = require('crypto');

const timestamp = Math.ceil(Date.now() / 1000);
const apiSecret = "Onboard API secret"; // Found in the Business Dashboard
const requestBody = JSON.stringify({ /* your request body */ });

const params = [`t=${timestamp}`, requestBody].join('&');
const signature = crypto.createHmac('sha256', apiSecret).update(params).digest('hex');

console.log(`x-signature: ${signature}`);

Making a secure API request

Include the following headers in your request:
x-api-key: <your-api-key>
x-signature: <computed-signature>
x-timestamp: <epoch-timestamp>
x-timestamp must be within 30 seconds of the current time. Older timestamps will result in a 403 Forbidden error.
Unauthorized Requests: Endpoints that require authentication will return a 401 Unauthorized status code for missing or invalid credentials.
I