Setup
This page walks through the backend integration end to end: from the session token your app needs to start the SDK, to the final liveness result.

Requirements
Mobile Key
Steps 1 and 3
client-id and client-secret from the Trust Platform (Settings → API configurations → Mobile Keys). Used to request the session token and to verify the signedResponse. See Authentication.
Application
Steps 4 and 5
An application from the Trust Platform (Settings → API configurations → Applications) with OAuth2 credentials (client_id and client_secret), used to obtain an access token.
Permission
Step 5
The scope v1-faces-liveness-attempts:read granted to the application.
The Trust Platform paths above apply to the US region. For the Brazil region, see Regions.
Regions
Face Liveness Lite runs in two isolated regions. Pick one and use its hosts in every step.
Web (session token)
https://web.us.prd.caf.io
https://web.sa.prd.caf.io
API (access token and result)
https://api.us.prd.caf.io
https://api.sa.prd.caf.io
To use the Brazil region, contact Certta. Certta provides the Mobile Key and the application credentials for Brazil.
The SDK selects the region from the session token, so the app needs no region setting. For the minimum SDK versions, see Regions.
Request the session token
Your backend signs an Authentication Token with the Mobile Key and exchanges it for a session token. For the full details, see Authentication.
The Authentication Token is a JWT signed with the Mobile Key client-secret, with this payload:
iss
Yes
The Mobile Key client-id.
exp
No
Expiration time (Unix timestamp). Keep it short.
Send it to the session token endpoint:
Base URL
https://web.us.prd.caf.io/bff (US) or https://web.sa.prd.caf.io/bff (Brazil)
Path
GET /session-tokens
Authorization
Bearer <AUTHENTICATION_TOKEN>
Response
requestId
String
Identifier of this request. Use it when you contact support.
sessionToken
String
Token used to start the SDK in the app.
tokenId
String
Identifier of the issued token. Store it — you need it to validate the signedResponse in step 3.
Send the sessionToken to the app and keep the tokenId on your backend, linked to the user's journey. The app passes the sessionToken to the SDK as mobileToken, together with the personId:
Platform
Where the sessionToken goes
iOS
setup(mobileToken:personId:…) — see Starting Liveness Flow
Android
CafLivenessConfig(mobileToken = …) — see Starting Liveness Flow
Request a new session token right before each liveness attempt. Treat each tokenId as single-use: your backend accepts only one signedResponse for it (see step 3).
Receive the signedResponse
When the capture ends, the SDK returns a signedResponse to your app, which must forward it to your backend. It is returned on success and on failure:
iOS
didFinishWithSuccess(livenessResult:)
didFinishWithFailure(type:description:signedResponse:)
Android
LivenessLiteEvent.Success(signedResponse)
LivenessLiteEvent.Failure(signedResponse, type, description)
The signedResponse is a signed JWT. Its payload contains:
livenessAttemptId
String
Unique identifier of the liveness attempt. Used to retrieve the result in step 5.
tokenId
String
Identifier of the session token that started this capture. Must match the tokenId stored in step 1.
sessionId
String
Identifier of the registered liveness session.
personId
String
Identifier of the person associated with the attempt.
Validate the signedResponse
Before you use any value from the payload, check:
Signature — the JWT verifies with your Mobile Key
client-secret, using only theHS256algorithm.tokenId— it is present and equal to thetokenIdyou stored in step 1.Single use — the
tokenIdwas not used before. Mark it as used in the same operation as this check, so that two concurrent requests cannot both pass.personId(optional) — it is equal to thepersonIdyour app passed to the SDK.
If a check fails, reject the signedResponse. See Error Handling. The payload has no exp claim: do not require one.
Example in Node.js, with the jsonwebtoken library:
Obtain an access token
The result endpoint uses OAuth2. Exchange the application credentials for an access token:
Base URL
https://api.us.prd.caf.io (US) or https://api.sa.prd.caf.io (Brazil)
Path
POST /oauth2/token
Content-Type
application/x-www-form-urlencoded
grant_type
String
Yes
Fixed value: client_credentials
client_id
String
Yes
ID of the application
client_secret
String
Yes
Secret of the application
Do not send a scope parameter. The access token carries the scopes granted to the application.
expires_in is the token lifetime in seconds. Reuse the token until it expires, then request a new one.
Retrieve the result
Base URL
https://api.us.prd.caf.io (US) or https://api.sa.prd.caf.io (Brazil)
Path
GET /v1/faces/liveness/attempts/{attemptId}/await
This endpoint waits on the server until the attempt finishes processing and returns the result in a single call. When the result is ready, the response carries a final status: COMPLETED or FAILED. If the result is not ready within the server's wait, the endpoint returns attempt_not_found; see Error Handling.
Path parameters
attemptId
String
Yes
The livenessAttemptId read from the verified signedResponse in step 3.
Headers
Authorization
String
Yes
Bearer access token from step 4, of an application that has v1-faces-liveness-attempts:read.
Example
Timing
Set your HTTP client timeout above 15 seconds: the call can wait on the server while the attempt is processed.
Call the endpoint as soon as your backend has the
livenessAttemptId. Later calls return the same result, but take longer.
The response fields are described in Result Reference. To decide what to do with the result, see Failure Handling.
Before you go live
Last updated

