Gestão de Sessão

Ao criar uma sessão de autenticação, basta utilizar o link gerado para iniciar o fluxo de cadastro do usuário. Isso pode ser feito através do envio do link ou do uso dele diretamente em seu website, com ferramentas como iframe.

Objeto de retorno

O objeto de retorno da criação e resgate de uma auth_session contém as seguintes informações:

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",
  }

Esse objeto é retornado no enpoint de resgate da sessão:

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

Descrição do campos de resposta:

nome	tipo	descrição
id	string	Id da sessão.
status	string	Status da sessão.
expiration_date	date	Data de expiração da sessão. Após essa data, a sessão é invalidada.
step_data	object	Objeto de retorno dos eventos da sessão.
settings	object	Objeto de configuração da sessão.
auth_session_hash	string	Hash de identificação da sessão.
step	string	Etapa atual do usuário.
auth_session_url	string	Url capaz de coletar as informações do cadastro.
token	string	Token de autenticação da sessão.
token_expiration_date	date	Data de expiração do token temporário de autenticação. Padrão definido para 2 horas após a geração da sessão.

Status

Possíveis status:

pending
completed
expired

Objeto step_data

Objeto que contém os dados coletados de cada step.

Informação

Caso o step não esteja listado nas settings da sessão, o mesmo não estará presente como campo do objeto step_data

face_recognition

Nome	Tipo	Descrição
image_key	string	Chave de identificação da etapa de face_recognition.
event_date	date	Data de finalização da etapa.

personal_document

Nome	Tipo	Descrição
document_template	string	Template selecionado pelo usuário no momento da coleta do documento.
ocr_keys	list	Lista com as chaves de identificação de cada documento coletado.
event_date	date	Data de finalização da etapa.

device_scan

Nome	Tipo	Descrição
session_id	string	Chave de identificação da etapa de scan do dispositivo.
event_date	date	Data de finalização da etapa.

Autenticação do fluxo web

Para garantir mais segurança para a aplicação, retornamos um token temporário para a página web. É possível resgatar o token, ou gerar um novo através do endpoint:

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

Request Body

{}

Response Body

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

Assim, caso o token tenha expirado, é possível seguir com a sessão de autenticação gerando um novo token.

Comunicação com a página web

A página web poderá ser integrada através de uma ferramenta chamada iframe. Da seguinte maneira:

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

⚠️ Configuração Obrigatória

Para que o iframe funcione corretamente em produção (auth-session.caas.qitech.app) e sandbox (auth-session.sandbox.caas.qitech.app), é necessário configurar o seguinte header de Permissions-Policy:

Configuração com URLs específicas (recomendado):
{
  "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\")"
}
Configuração alternativa (menos restritiva):
{
  "key": "Permissions-Policy",
  "value": "geolocation=*, microphone=*, camera=*, fullscreen=()"
}
Essa configuração deve ser aplicada no servidor que hospeda a página que contém o iframe para garantir que as permissões necessárias sejam concedidas.

Caso o link seja chamado dessa maneira, a página web irá enviar mensagens de retorno para a página que a requisitou. As possíveis mensagens de retorno são:

success
canceled
invalid_token
expired

Que podem ser acessadas da seeguinte maneira:

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
            }
        });

Finalização do fluxo

Este serviço irá gerenciar o fluxo de coleta de dados de autenticação, que poderão ser utilizados nos demais serviços. Para mais informações de como utilizar as chaves retornadas nos demais produtos, segue o exemplo da análise cadastral de pessoa física Análise Cadastral

Gestão de Sessão

Objeto de retorno​

Status​

Objeto step_data​

Autenticação do fluxo web​

Comunicação com a página web​

Finalização do fluxo​