Authentication
SDK authentication strategies — session, OAuth, client-secret, and API key.
Type tables on this page are generated directly from the SDK source code at build time.
The SDK supports four authentication strategies. Set via auth in GlobalConfig (applies to all components) or per-component in MountConfig.
Session Auth (Default)
Cookie-based session authentication. The iframe checks the session endpoint with credentials: 'include'. On failure, a login popup opens.
VisaAcceptance.init({
auth: { type: 'session' }
});Prop
Type
OAuth / Bearer Token
Host provides an async token factory. Called before mounting and on every token expiry. Supports proactive JWT refresh.
VisaAcceptance.init({
auth: {
type: 'oauth',
getToken: () => authService.getAccessToken(),
refreshToken: () => authService.refreshAccessToken(),
expiryBufferSeconds: 60,
}
});Prop
Type
Client Secret
Pre-issued secret delivered to the iframe via secure postMessage. No popup needed.
VisaAcceptance.init({
auth: {
type: 'client-secret',
secret: 'cs_live_abc123',
refreshSecret: () => secretService.rotate(),
}
});Prop
Type
API Key
Static key injected as X-API-Key header. Simplest strategy.
VisaAcceptance.init({
auth: { type: 'api-key', apiKey: 'ak_live_xyz789' }
});Prop
Type
Auth Lifecycle
┌─────────────┐ ┌─────────┐ ┌──────────────────────┐ ┌───────────────┐
│ INITIALIZING │ ──→ │ MOUNTED │ ──→ │ CREDENTIAL_DELIVERED │ ──→ │ AUTHENTICATED │
└─────────────┘ └─────────┘ └──────────────────────┘ └───────────────┘
│ │
│ (session invalid) (token expires)
▼ ▼
┌──────────────┐ ┌─────────────────┐ ┌──────────────────────────┐
│ AUTH_REQUIRED │ ──→ │ AUTH_IN_PROGRESS │ │ TOKEN_REFRESH_IN_PROGRESS │
└──────────────┘ └─────────────────┘ └──────────────────────────┘
│ │
└──── AUTHENTICATED ◄─────┘The exact path depends on the auth strategy. Session auth goes through AUTH_REQUIRED → AUTH_IN_PROGRESS. Token-based strategies (OAuth, Client Secret) go through CREDENTIAL_DELIVERED. See the State Machine reference for the full transition diagram.