# QI Tech — Risk Solutions › KYC Session Manager Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 5 página(s). Índice: - Session Creation (/en/documentation/caas/auth_session_manager/auth_session) - Authentication (/en/documentation/caas/auth_session_manager/authentication) - HTTP Status (/en/documentation/caas/auth_session_manager/http_status) - Introduction (/en/documentation/caas/auth_session_manager/introduction) - Session Management (/en/documentation/caas/auth_session_manager/retrieve_session) --- # Session Creation URL: /en/documentation/caas/auth_session_manager/auth_session 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 ```json { "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). ### 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 ```json { "id": "12345", ... } ``` Response Body ```json { "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 URL: /en/documentation/caas/auth_session_manager/authentication > To authenticate a call, use the following code: ```shell # In the shell, you only need to add the appropriate header to each request curl "api_endpoint_here" -H "Authorization: EXAMPLE-OF-API-KEY" ``` > Replace the API Key 'EXAMPLE-OF-API-KEY' with your key, which should be obtained from our support team. We use an API Key to allow access to our API. It has probably already been sent to you by email. If you have not yet received your key, send an email to suporte.caas@qitech.com.br . Our API expects to receive the API Key in all requests to our server in a header like the one below: `Authorization: EXAMPLE-OF-API-KEY` :::info **Attention** You must replace EXAMPLE-OF-API-KEY with your key, which should be obtained from our support team. ::: --- # HTTP Status URL: /en/documentation/caas/auth_session_manager/http_status All QI Tech APIs use the following standardization for HTTP response status codes, in accordance with RFC 7231 : Status HTTP | Meaning | Description ---------- | ------- | --------------------------------- 400 | Bad Request | The request sent has a formatting error. In most cases, we return an explanation in the response body indicating where the error is. 401 | Unauthorized | There was an authentication problem; verify that the API Key is correct and in the correct header, as described in the Authentication section. 403 | Forbidden | The endpoint accessed is for internal use and is not available for this API Key. 404 | Not Found | The requested data was not found using the key provided. This status is also returned when an invalid endpoint is requested. 405 | Method Not Allowed | The HTTP method used does not apply to the endpoint used. 406 | Not Acceptable | The data sent in the request body is invalid. In general, this means the data sent is not valid JSON. 409 | Conflict | The request id matches an id that was already processed previously. This status is returned in the case of duplicate requests sent to the server. 500 | Internal Server Error | We had a problem processing this request; when we encounter this error our specialists are automatically notified and begin analysis and resolution immediately. 503 | Service Unavailable | You have encountered an outage, planned or not, of our server infrastructure. --- # Introduction URL: /en/documentation/caas/auth_session_manager/introduction Welcome to the QI Tech Authentication Session Management API! This API was designed to control the complete user KYC flow! This service organizes the authentication process, enabling the creation of KYC registration sessions with customized flows and use of other QI Tech authentication services: * Device Scan * Face Recognition * OCR This way, it is possible to start the registration information collection flow through the link returned by the API. Once started, the web page will be responsible for guiding the user through the KYC steps defined in that session. Furthermore, by being directly integrated with the other services described above, it is able to collect the information necessary to complete the authentication flow. With this information, it will be possible to perform the desired analysis on other QI Tech services, such as individual registration or a pre-transactional analysis, for example. ## Problems? We are not a company that hides behind an API! Contact our support and we will respond as quickly as possible. Feel free to call us if you want a quick response! ### We Love Feedback Even if you have already resolved your issue or if it is very simple (even a typo or inadequate organization that you have noticed), send us an email so we can make the documentation increasingly more practical and the next person won't have to suffer the same pains you did! ## Environments We have two environments for our clients. The base URLs for the APIs are: * Production - `https://api.caas.qitech.app/auth_session_manager/` * Sandbox - `https://api.sandbox.caas.qitech.app/auth_session_manager/` :::danger Important Notice! Real data from individuals and/or legal entities must not be used in QI Tech's Sandbox environments. ::: In the Sandbox environment, submitted analyses are not charged and are responded to according to the rule configured for the event. ## HTTPS Only For security reasons, all communication with QI Tech APIs must be carried out using HTTPS. To ensure that, due to inattention or any other reason, no HTTP calls occur, this server only makes port 443 available with TLS 1.2 communication. Calls made using other protocols will be automatically denied. --- # Session Management URL: /en/documentation/caas/auth_session_manager/retrieve_session 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 ```json { "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. :::info 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 ```json { "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 ```json { "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](mailto:suporte.caas@qitech.com.br) 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. :::info **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: ```html ``` > ⚠️ **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):** > ```json > { > "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):** > ```json > { > "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: ```javascript 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](https://docs.qitech.com.br/documentation/caas/onboarding/query_registration)