Unity API authentication (backend to backend)

All Unity backend APIs are authenticated with two request headers, derived from credentials shared during onboarding.

Integration credentials

Every partner receives three values from their smallcase business POC. You'll need these before calling any Unity API from your backend.

Credential	Description
Partner name	Your partner identifier. Must match exactly what was shared by your POC. Used as the `iss` claim in the JWT.
Secret	Used to sign the JWT sent in the `x-gateway-authtoken` header. Keep this confidential.
API Secret	Sent as-is in the `x-gateway-secret` header.

To obtain these, reach out to your business POC.

Request headers

Send both of these headers on every backend to backend API request:

Header	Value
`x-gateway-secret`	The API Secret (plain string).
`x-gateway-authtoken`	A JWT signed with your Secret, using the payload below.

JWT payload for x-gateway-authtoken

Algorithm: HS256, signed with your Secret.
Claims: iss = your partner name (exactly as shared); exp = a short-lived expiry (e.g. now + 5 minutes) so tokens rotate frequently.

{
  "iss": "<partner-name>",
  "exp": 1730812800
}

Set exp to a Unix timestamp a few minutes in the future. Generate a fresh JWT per request (or cache and refresh before expiry), and keep your server clock in sync so exp is accepted.

Note: This backend-API auth token (x-gateway-authtoken) is different from the Interaction Token described below. Both are JWTs signed with your shared Secret, but the auth token authenticates server-to-server API calls, while the Interaction Token identifies a specific user journey when initializing the SDK.

IP Whitelisting

Your backend can only call Unity if your backend's public IP is whitelisted with us. Share your IP address with your business POC for whitelisting. You can whitelist multiple IP addresses, if required.

Loans SDKs - Interaction Token (JWT) generation

All Loans SDKs use JWT tokens to identify and launch LAMF and LAS journeys. They are called Interaction Tokens.

A JWT contains three components -

JWT Header
This contains the encoding algorithm of a JWT. Use HS256 for our integration
JWT Signature
Each partner is given a shared secret (aka JWT secret). Use the shared secret to sign the JWT.
JWT Payload
This is used to identify the kind of LAMF or LAS user journey to be triggered. A typical Interaction Token will have the following payload -

{
  "interactionId": "INT64ff11531abc58c28af23ffc",
  "iss": "<your-gateway-name>",
  "exp": 1696981514
}

...and the Interaction Token itself (signed with secret "have-a-good-day") will look something like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlcmFjdGlvbklkIjoiSU5UNjRmZjExNTMxYWJjNThjMjhhZjIzZmZjIiwiaXNzIjoiPHNhbXBsZS1nYXRld2F5PiIsImV4cCI6MTY5Njk4MTUxNH0.RyxCHZmYb_SuScoP9FV0qPJo6UxrtgxDKb_8elkn28g

Interaction token expiration (JWT expiry)

An interaction token (JWT) MUST have an expiration set in exp. We recommend keeping a short expiration of few minutes.

Interaction ID in itself does not have expiration but can only be used once on SDK. The same Interaction ID cannot be used in twice to create interaction token JWT and initialise the Loans SDK again.

Error handling

Error handling

Webhook

LAMF webhooks

Getting started with LAMF & LAS