Authentication & Tokens
API_KEY (server) + Bootstrap Token (client) + internal access/refresh.
The security model (read this once, save yourself pain)
Rule #1: API_KEY is server-only
The tenant API_KEY must never be used in:
- frontend code
- mobile apps
- browser network calls
- public repositories
Your integration should always follow:
- Backend authenticates with API_KEY
- Backend mints a Bootstrap Token scoped to (tenant + application + borrower + journey)
- Frontend passes Bootstrap Token to the SDK UI
- The embedded checkout (iframe) handles all access/refresh mechanics internally
Tokens: what they are and who holds them
API_KEY (API Key)
Who holds it: your backend
Purpose: authenticate your system as an onboarded tenant
Lifetime: long-lived (rotate periodically)
Bootstrap Token
Who holds it: tenant frontend briefly (memory) → SDK → iframe
Purpose: start or resume an embedded checkout session securely
Lifetime: short-lived and one-time use
Access Token
Who holds it: the embedded checkout (inside the iframe)
Purpose: call Credit APIs during the journey
Lifetime: short-lived
Refresh Token
Who holds it: the embedded checkout (inside the iframe)
Purpose: mint new access tokens without user friction
Lifetime: longer-lived, rotated
Why journeys can last days without long-lived browser tokens
The Journey is a server-side construct and can last for days. Tokens are short-lived credentials that can be re-issued safely as needed. To resume a journey, you mint a new Bootstrap Token for the same journey scope.
Practical lifecycle guidance
A borrower may return tomorrow
No problem:
- Your backend mints a new Bootstrap Token
- The SDK opens the same journey
- The embedded checkout resumes from server state
You should store journey references server-side
Recommended:
- Store
{ borrowerReference, journeyReference }(or IDs) in your DB - On “resume”, mint a fresh Bootstrap Token
- Avoid keeping these identifiers in localStorage if you don’t need to
Passing the API_KEY
Most integrations standardize on one of these:
Authorization: Bearer <API_KEY>X-API-Key: <API_KEY>
Use whichever your dashboard/API reference specifies.
Environment separation
You should have separate credentials and allowlists for:
- Test / Non-production
- Production
This prevents accidental production traffic during development.
Rotation & compromise handling
Production recommendations:
- Rotate API_KEY on a schedule (e.g., quarterly) and immediately on suspicion.
- Support multiple active keys during rotation windows.
- Log token mint requests with correlation IDs (but never log the token itself).