LogoLogo
Useful links
  • Home
  • Product guides
  • API
  • SDKs
  • Overview
  • First steps
  • ANDROID
    • Getting Started with the SDK
    • Standalone Modules
      • Document Detector
        • Release Notes
        • Current Version
        • Requirements
        • Gradle Dependencies
        • Gradle Source Code
        • Setting up the SDK
          • Setting properties
          • Capture Stages
          • Messages Settings
          • Customization
          • Security Settings
          • Detection Steps
          • Upload Mode
          • Advanced Settings
            • Proxy configuration
            • Preview configuration
        • Start Document Detection
        • Source Code
        • Google security form
        • Reduce SDKs size
        • SDKs response
        • References
        • FAQ
      • Face Liveness
        • Release Notes
        • Current Version
        • Requirements
        • Gradle Dependencies
        • Gradle Source Code
        • SDK Lifecycle
        • Building the SDK
        • Start Liveness Verification
        • Source Code
        • References
        • Advanced Features
        • FAQ
      • Face Authenticator
        • Release Notes
      • Smart Auth
        • Release Notes
        • Current Version
        • Requirements
        • Gradle Dependencies
        • Gradle Source Code
        • Permissions
        • SDK Lifecycle
        • Building the SDK
        • Start Smart Authentication
        • Source Code
        • References
        • FAQ
      • Face Liveness (deprecated)
        • Release Notes
  • iOS
    • Getting Started with the SDK
    • Standalone Modules
      • Document Detector
        • Release Notes
        • Current Version
        • Requirements
        • Installing the SDK
        • Setting up the SDK
          • Setting properties
          • Messages Settings
          • Customization
          • Detection Steps
          • Upload Mode
          • Advanced Settings
            • Proxy configuration
            • Preview configuration
        • Start Document Detection
        • References
        • FAQ
      • Face Liveness
        • Release Notes
        • Installation
        • Current Version
        • Requirements
        • SDK Lifecycle
        • Building the SDK
        • Start Liveness Verification
        • Source Code
        • References
        • FAQ
      • Face Authenticator
        • Release Notes
        • Installation
        • Current Version
        • Requirements
        • Building the SDK
        • Start the SDK
        • References
        • FAQ
      • Smart Auth
        • Release Notes
        • Installation
        • Current Version
        • Requirements
        • SDK Lifecycle
        • Building the SDK
        • Start Smart Authentication
        • Source Code
        • References
        • FAQ
      • Face Liveness (deprecated)
        • Release Notes
  • REACT NATIVE
    • Standalone Modules
      • Document Detector
        • Release Notes
        • Current Version
        • Requirements
        • Installation
        • Hooks
        • Start Document Verification
        • Source Code
        • TypeScript References
        • Customizing Style
        • FAQ
      • Face Liveness
        • Release Notes
        • Current Version
        • Requirements
        • Installation
        • Hooks
        • Start Liveness Verification
        • Source Code
        • TypeScript References
        • FAQ
      • Face Authenticator
        • Release Notes
        • Current Version
        • Requirements
        • Installation
        • Hooks
        • Start Authentication Verification
        • Source Code
        • TypeScript References
        • FAQ
      • Smart Auth
        • Getting started
        • Release notes
        • Using Native Modules
          • Requirements
          • Gradle Source Code
          • Podfile Source Code
          • Native Module Android
          • Native Module iOS
          • Import Native Modules
          • Source Code
          • TypeScript References
          • FAQ
        • Using Expo Modules
          • Requirements
          • Create Local Expo Module
          • Gradle Source Code
          • Podspec Source Code
          • Native Module Android
          • Native Module iOS
          • Import Expo Modules
          • Source Code
          • TypeScript References
          • FAQ
  • WEB (JAVASCRIPT)
    • Standalone Modules
      • Document Detector
        • Getting started
        • SDK builder options
          • Analytics
          • Appearance
          • Messages
        • SDK methods
        • Event listeners
        • Customization
        • Release notes
      • Face Liveness
        • Customization
        • Release notes
      • Face Authenticator
        • Customization
        • Release notes
      • Smart Auth
        • SDK errors
        • Customization
        • Release notes
LogoLogo

2025 © Caf. - All rights reserved

On this page
  • Reverse Proxy
  • SDK Returns
  1. iOS
  2. Standalone Modules
  3. Face Authenticator

References

CafFaceAuth Options

Parameter
Required
Default Value

startFaceAuthSDK(viewController: UIViewController, mobileToken: String, personId: String)

  • mobileToken: Usage token associated with your CAF account

  • personId: Identifier of the user who will perform the face liveness verification. It's recommended to use the user's identification document in this field, such as their CPF (Brazilian document ID), but it could be any other value.

Yes

You must provide this information.

.setStage(stage: CAFStage)

Used to redirect the SDK to the desired environment in caf api. It has the following options: .beta or .prod.

No

.prod

.setFilter(filter: Filter)

Set the camera filter applied to the camera preview. It has the following options: .natural or .lineDrawing

No

.lineDrawing

.setLoadingScreen(withLoading: Bool)

This boolean parameter determines whether the loading screen will be implemented via a delegate or if you will use the default screen. If set to 'true,' the loading screen will be a standard SDK screen. In the case of 'false,' you should use the 'LoadingScreen' session and implement the delegates.

No

false

.setImageUrlExpirationTime(time: Time)

Use to change the default image URL expiration time to retrieve the scan capture. It has the following options: .threeHours, .thirtyDays or .thirtyMin.

No

30 min

.setAuthBaseUrl(authBaseUrl: String)

Enables the use of a reverse proxy to execute SDK's authentications. Sets the base URL for authentication; protocol must be HTTPS. Adds a trailing slash if missing.

No

Default Caf URL

.setLivenessBaseUrl(livenessBaseUrl: String)

Enables the use of a reverse proxy to execute face liveness checks. Sets the base URL; protocol must be WSS. Adds a trailing slash if missing. Requires certificates set via .setCertificates for security.

No

Default IProov URL

.setCertificates(certificates: [String])

Sets the SHA256 Base64-encoded protocols for secure communication in reverse proxy implementations. Required when using custom URLs for authentication or face liveness checks.

No

Empty list

Reverse Proxy

To configure reverse proxy settings, please follow these instructions:

CafFaceAuth Reverse Proxy

  • Set your proxy to communicate with the URL that corresponds to the CAFStage you are using:

    • CAFStage.PROD -> https://api.public.caf.io/v1/sdks/faces/

    • CAFStage.BETA -> https://api.public.beta.caf.io/v1/sdks/faces/

    • CAFStage.DEV -> https://api.public.dev.caf.io/v1/sdks/faces/

  • Use the method .setLivenessBaseUrl to set the URL on which FaceLiveness should run.

    • The URL's protocol must be WSS.

  • Use the .setCertificates method to set the certificates, which should be the base64-encoded SHA-256 hash of the certificate's Subject Public Key Info.

    • Certificates are required for the FaceLiveness reverse proxy to work properly.

    faceAuthenticator = FaceAuthSDK.Build()
    .setLivenessBaseUrl("wss://my.proxy.io/ws/")
    .setCertificates(certificates: [
        "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
        "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
        "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
    ])
    .build()

Authentication reverse proxy

  • Set your proxy to communicate with `wss://us.rp.secure.iproov.me/ws´.

  • Use the method .setAuthBaseUrl to set the URL on which the authorization requests must run.

    • The URL's protocol must be HTTPS.

    faceAuthenticator = FaceAuthSDK.Build()
        .setAuthBaseUrl("https://my.proxy.io/v1/faces/")
        .build();

SDK Returns

Success cases

At the end of a successful execution, you will receive an object of type FaceAuthenticatorResult. This object carries a signedResponse property containing a JWT token with the execution result. This token should be decrypted to obtain the execution results details.

faceAuthenticatorResult.signedResponse

SignedResponse params

Event
Description

requestId

Request identifier.

isAlive

Validation of a living person, identifies whether the user passed successfully or not.

isMatch

Face match validation result.

token

Request token.

userId

User identifier provided for the request.

imageUrl

Temporary link to the image, generated by our API.

personId

User identifier provided for the SDK.

sdkVersion

Sdk version in use.

iat

Token expiration.

message

Return message.

The isAlive parameter is VERY IMPORTANT, as it dictates whether the validation process proceeds or halts. When isAlive: true, the user gains passage to continue their journey; conversely, if isAlive: false, the user is deemed invalid and access to further stages of the journey should be denied. Additionally, the isMatch parameter indicates the success or failure of the face match, returning isMatch: true for successful matches and isMatch: false otherwise. This parameters plays a pivotal role in guiding the flow of operations.

Error cases

In the event of execution errors, you will receive an object of type FaceAuthenticatorErrorResult. This object encompasses an enum containing the errorType, and a description.

ErrorType
Description

unsupportedDevice

This error may occur if the device hardware or software does not meet the minimum requirements for facial recognition functionality.

cameraPermission

This error typically occurs when the user denies access to the camera or if the app lacks the necessary permissions.

networkException

This error may occur due to various network issues such as a lack of internet connection, server timeouts, or network congestion.

tokenException

This error may occur if the provided authentication token is invalid, expired, or lacks the necessary permissions to perform facial recognition tasks.

serverException

This error is typically returned when there is an issue with the server processing the facial recognition request. This could include server-side errors, misconfigurations, or service interruptions.

Last updated 2 months ago

Within the signedResponse, the parameter isAlive defines the execution of liveness, where true is approved and false is rejected ( will be returned).

Error case