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

  {
    "token_expiration_seconds": 3600
  }

O objeto de token tem somente um campo opcional:

Nome	Tipo	Descrição
token_expiration_seconds	interger	Tempos de expiração do token de sessão em segundos. (deve esstar entre 1 e 172800, máximo de 48 horas. O valor padrão é 1800)

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.

Webhook

A finalização da sessão será notificada por meio do envio de webhook. Para tanto, é necessário, por meio da equipe do suporte, configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma signature_key que será utilizada para assinar a requisição. Vale ressaltar que todos os envios de webhook serão feitos para um único endpoint.

Atenção

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.

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​