Session Management

When creating an authentication session, simply use the generated link to start the user registration flow. This can be done by sending the link or using it directly on your website, with tools such as iframe.

Response object

The response object from creating and retrieving an auth_session contains the following information:

Response Body

  {
    "id": "12345678",
    "status": "pending",
    "expiration_date": "2025-12-11T11:37:15.12-03:00",
    "step_data": {
      "face_recognition": {
        "image_key": "65441d8d-015a-4a0f-97b6-b7d4fc5619b7",
        "event_date": "2025-12-11T11:37:15.12-03:00"
      },
      "personal_document": {
          "document_template": "rg",
          "ocr_keys": [
            "e13c71d0-ae0e-48e2-8c42-26f997412039",
            "3991b716-0980-409f-8e33-e3a8dd9a671c"
          ],
          "event_date": "2025-12-11T11:37:15.12-03:00"
      },
      "device_scan": {
          "session_id":  "4d450227-c77c-4487-830b-42dcd127798a",
          "event_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": "fc0aaa39-1c21-1bc1-a5a1-39a7ca01121b",
    "token_expiration_date": "2025-12-10T11:37:15.12-03:00",
  }

This object is returned by the session retrieval endpoint:

GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}

Response fields description:

name	type	description
id	string	Session ID.
status	string	Session status.
expiration_date	date	Session expiration date. After this date, the session is invalidated.
step_data	object	Object containing the session event results.
settings	object	Session configuration object.
auth_session_hash	string	Session identification hash.
step	string	User's current step.
auth_session_url	string	URL used to collect registration information.
token	string	Session authentication token.
token_expiration_date	date	Expiration date of the temporary authentication token. Default set to 2 hours after session creation.

Status

Possible status values:

pending
completed
expired

step_data object

Object containing the data collected from each step.

Information

If the step is not listed in the session settings, it will not be present as a field in the step_data object

face_recognition

Name	Type	Description
image_key	string	Identification key for the face_recognition step.
event_date	date	Step completion date.

personal_document

Name	Type	Description
document_template	string	Template selected by the user at document collection time.
ocr_keys	list	List of identification keys for each collected document.
event_date	date	Step completion date.

device_scan

Name	Type	Description
session_id	string	Identification key for the device scan step.
event_date	date	Step completion date.

Web flow authentication

To ensure greater security for the application, we return a temporary token for the web page. You can retrieve the token or generate a new one through the endpoint:

POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token

Request Body

  {
    "token_expiration_seconds": 3600
  }

The token object has only one optional field:

Name	Type	Description
token_expiration_seconds	integer	Session token expiration time in seconds. (must be between 1 and 172800, maximum 48 hours. Default value is 1800)

Response Body

  {
    "id": "12345678",
    "token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3",
    "token_expiration_date": "2025-12-10T13:37:15.12-03:00",
  }

Thus, if the token has expired, you can continue with the authentication session by generating a new token.

Webhook

Session completion will be notified via webhook. To do so, it is necessary to configure, through the support team, an endpoint address where we will send the notifications and also a signature_key that will be used to sign the request. It is worth noting that all webhook deliveries will be sent to a single endpoint.

Attention

For security reasons, all Webhook requests will only be made to endpoints served over HTTPS.

Communication with the web page

The web page can be integrated through a tool called iframe. In the following way:

<iframe id="iframe" src="" href="{auth_session_url}" allow="camera; microphone" referrerPolicy="no-referrer"></iframe>

⚠️ Required Configuration

For the iframe to work correctly in production (auth-session.caas.qitech.app) and sandbox (auth-session.sandbox.caas.qitech.app), it is necessary to configure the following Permissions-Policy header:

Configuration with specific URLs (recommended):
{
  "key": "Permissions-Policy",
  "value": "geolocation=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), microphone=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), camera=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), fullscreen=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\")"
}
Alternative configuration (less restrictive):
{
  "key": "Permissions-Policy",
  "value": "geolocation=*, microphone=*, camera=*, fullscreen=()"
}
This configuration must be applied on the server that hosts the page containing the iframe to ensure that the necessary permissions are granted.

If the link is called in this way, the web page will send return messages to the page that requested it. The possible return messages are:

success
canceled
invalid_token
expired

Which can be accessed in the following way:

window.addEventListener("message", (event) => {
            if (event.data === "canceled") {
              //close iframe
            }
            if (event.data === "invalid_token") {
              //close iframe
            }
            if (event.data === "success") {
              //close iframe
            }  
            if (event.data === "expired") {
              //close iframe
            }
        });

Flow completion

This service will manage the authentication data collection flow, which can be used in other services. For more information on how to use the returned keys in other products, see the individual registration analysis example Registration Analysis

Session Management

Response object​

Status​

step_data object​

Web flow authentication​