For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Backend integration flow: session token, capture, signedResponse validation, access token and result

Requirements

Requirement
Used for
Description

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.

The Mobile Key client-secret and the application client_secret are different credentials. The first one signs the Authentication Token and verifies the signedResponse; the second one obtains the access token to read the result.

Regions

Face Liveness Lite runs in two isolated regions. Pick one and use its hosts in every step.

Host
US
Brazil

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.

1

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:

Claim
Required
Description

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

Field
Type
Description

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).

2

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:

Platform
Success
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:

Field
Type
Description

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.

The signedResponse does not carry isAlive or images. The SDK does not wait for the result either: your backend retrieves it in step 5.

3

Validate the signedResponse

Before you use any value from the payload, check:

  1. Signature — the JWT verifies with your Mobile Key client-secret, using only the HS256 algorithm.

  2. tokenId — it is present and equal to the tokenId you stored in step 1.

  3. Single use — the tokenId was not used before. Mark it as used in the same operation as this check, so that two concurrent requests cannot both pass.

  4. personId (optional) — it is equal to the personId your 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:

4

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

Body field
Type
Required
Description

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.

5

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

Parameter
Type
Required
Description

attemptId

String

Yes

The livenessAttemptId read from the verified signedResponse in step 3.

Headers

Header
Type
Required
Description

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