Session Creation

The authentication session object is an entity that represents the user's authentication flow. Through this element, you can manage the registration information collection process.

Authentication Session Object Definition

Request Body

{
  "id": "12345678",
  "document_number": "111.111.111-11",
  "settings": {
    "steps": [
      {
        "step": "device_scan"
      },
      {
        "step":"face_recognition",
      },
      {
        "step":"personal_document",
        "show_success_screen": true,
        "show_introduction_screen": true,
        "document_templates":[
            "rg",
            "cnh",
            "cnh_digital"
        ]
      }
    ],
    "session_expiration_time_in_minutes": 120,
    "token_expiration_seconds": 3600,
    "open_mode": "iframe",
    "finish_screen": {
      "title": "Tudo certo!",
      "message": "Recebemos suas informações e daremos continuidade à sua solicitação."
    }
  }
}

All information exchanges for a session use the following definition for this object:

name	type	description
id	string	Session identifier. It is essential that this number be unique for each session (required)
document_number	string	CPF of the individual being registered, with dots and hyphens, according to the standard. (required)
settings	object	Object with the custom settings for the authentication session. If not sent, the company's default configuration will be used. When sent, it fully replaces the default configuration: fields missing from the object sent are not inherited from the default configuration.

settings object

The settings object contains the steps field which defines the sequence of authentication steps and their respective configurations. The accepted steps are:

device_scan
face_recognition
personal_document

The following fields are also accepted:

name	type	description
session_expiration_time_in_minutes	integer	Session expiration date. After this date, the session will not be valid.
token_expiration_seconds	integer	Session token expiration time in seconds. (must be between 1 and 172800, maximum 48 hours. Default value is 1800)
open_mode	string	Defines the session opening mode, for the message and buttons of the completion flow. (must be: "iframe" or "link").
finish_screen	object	Customizes the title and message of the screen shown to the user when the session is completed. Optional. See finish_screen.

finish_screen

The finish_screen object replaces the default texts of the web page's final screen. Both fields are optional, but when the object is sent it must contain at least one of them.

name	type	description
title	string	Title of the final screen. Between 1 and 100 characters.
message	string	Message shown below the title. Between 1 and 500 characters.

Behavior:

Texts are displayed as plain text: HTML, formatting and line breaks are not interpreted.
A missing field keeps the corresponding default text. Without finish_screen, the final screen shows the default texts.
The closing button and message are still defined by open_mode.

device_scan

The device_scan step indicates the execution of device information collection.
Has no additional configurations

face_recognition

The face_recognition step indicates the execution of the liveness proof flow collection through facial biometrics.
Has no additional configurations

personal_document

The personal_document step indicates the execution of the OCR flow collection for document reading.

name	type	description
document_templates	array	List of documents that can be collected in the registration flow. (required)
show_success_screen	boolean	Defines whether the success screen is shown in the document capture flow. Default value `true`.
show_introduction_screen	boolean	Defines whether the introduction screen is shown in the document capture flow. Default value `true`.

Accepted document_templates values:

Name	Type	Description
cnh	string	Capture of physical driver's license (CNH) FRONT and BACK (closed), in two steps
rg	string	Capture of physical ID card (RG) FRONT and BACK (closed), in two steps
cnh_digital	string	Submission of digital driver's license (pdf)
passport	string	Submission of Passport FRONT and BACK (closed), in two steps.
rne	string	Submission of National Registry of Foreigners FRONT and BACK (closed), in two steps.
crnm	string	Submission of National Migration Registry Card FRONT and BACK (closed), in two steps.
ctps	string	Submission of Work and Social Security Card FRONT and BACK (closed), in two steps.
others	string	Submission of any document exempt from validation FRONT and BACK (closed), in two steps.

Submit an Auth Session

Request Body

  {
    "id": "12345",
    ...
  }

Response Body

  {
    "id": "12345678",
    "status": "pending",
    "expiration_date": "2025-12-11T11:37:15.12-03:00",
    "settings": {
      ...
    },
    "auth_session_hash": "1cFL1vM",
    "step": "device_scan",
    "auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
    "token": "fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
    "token_expiration_date": "2025-12-10T11:37:15.12-03:00",
  }

To create a session, simply send an Auth Session object to the following endpoint:

POST https://api.caas.qitech.app/auth_session_manager/auth_session

Authentication Session Object Definition​

settings object​

finish_screen​

device_scan​

face_recognition​

personal_document​

Submit an Auth Session​