Authentication - Onboard Developer Documentation

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:

Retrieve your API key from the Business Dashboard after onboarding.
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:

Header	Description
x-api-key	Found in the Business Dashboard
x-signature	HMAC-SHA256 signature of the request body
x-timestamp	Unix 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.

Onboard Connect APIs

​Overview

​Authentication methods

Required Headers:

How to generate x-signature

Making a secure API request

Overview

Authentication methods

How to generate `x-signature`