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.