Authentication
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
Session-Based Authentication
Session-Based Authentication
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:
Example Request:
API Key Authentication
API Key Authentication
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 while others do not. Check the endpoint’s documentation to confirm.HMAC Signature Authentication
HMAC Signature Authentication
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):
Making a secure API request
Include the following headers in your request:
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.