> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Serviço

> Crie e encerre sessões de liveness Identy via API antes de iniciar o SDK

O serviço de sessões Identy autoriza o seu projeto e devolve ao seu cliente o token que o `LivenessIdentySDK` precisa para enviar a captura. Sem essa chamada, o SDK não consegue iniciar a verificação.

A base URL de produção é `https://api.valid.com/vendor-identy` e as rotas ficam abaixo de `/api/v1`. A autenticação usa a sua `x-api-key`, gerada na Plataforma ID — veja [Chaves de API](https://docs-platform.services-valid.com.br/plataforma/chaves-de-api.md).

> [!WARNING]
>
> **No Web, as origens da sua página precisam ser liberadas pela equipe da Valid antes de integrar.** Sem essa liberação, a captura não funciona na sua página. Veja os requisitos de [instalação Web](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/instalacao.md#autorize-suas-origens).

## Por que essa chamada existe

O `LivenessIdentySDK` é apenas um cliente: quem cria a sessão é o seu backend. Depois disso, o SDK usa o `sessionToken` emitido aqui para enviar a captura criptografada e receber o resultado — você não precisa implementar nem fazer proxy dessas outras chamadas.

* **`POST /api/v1/sessions`** — cria a sessão de liveness e devolve o `sessionToken` que o SDK usa para enviar a captura.
* **`POST /api/v1/sessions/:sessionId/fail`** — encerra uma sessão ativa quando o problema acontece **entre o SDK e o seu servidor**, antes da captura começar (usuário cancela na sua tela, validação de negócio rejeita, timeout do front, etc.), deixando o motivo registrado para auditoria.

> [!WARNING]
>
> **Faça essa chamada no seu backend, não no app ou na página.**
>
> A `x-api-key` da Plataforma ID identifica o seu projeto. Embuti-la no binário Android, no IPA ou no bundle JS de uma SPA é equivalente a publicar a chave — qualquer pessoa consegue extrair, reusar e gerar custo no seu projeto com ferramentas comuns (`jadx`, `Hopper`, DevTools).
>
> **A única integração segura é proxy-server-side:** o seu cliente fala com o seu backend, o seu backend fala com a Plataforma ID. O cliente nunca toca na `x-api-key`.

## Fluxo recomendado

**1. Cliente solicita sessão ao seu backend**

O app/web invoca um endpoint do seu próprio backend (com a sua autenticação de usuário), repassando o `ssid` quando o SDK o fornecer — veja [Metadados Complementares](#metadados-complementares).

**2. Seu backend chama POST /api/v1/sessions**

Servidor para servidor, com o header `x-api-key` e um `clientRequestId` novo. O serviço retorna `sessionId` e `sessionToken`.

**3. Seu backend devolve os tokens ao cliente**

Envie ao cliente apenas `sessionId` e `sessionToken`. Mantenha `deviceScore`, `deviceSignals` e geolocalização no seu backend.

**4. Cliente inicia o Liveness com esses tokens**

O `LivenessIdentySDK` usa os tokens para enviar a captura. Veja a implementação [Web](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao.md), [Android](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/implementacao.md) ou [iOS](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/implementacao.md).

**5. Se a captura falhar, tente novamente**

Cada sessão aceita **uma** captura. Para tentar de novo, crie uma **nova sessão** — no Web, basta chamar `run()` outra vez, que chama o seu `onInit` novamente.

**6. Se o problema for entre o SDK e o seu servidor, falhe a sessão**

Caso o usuário cancele ou o seu backend rejeite o fluxo antes da captura começar, chame `POST /api/v1/sessions/:sessionId/fail`. Sessões não finalizadas também expiram sozinhas após 10 minutos.

> [!NOTE]
>
> Hoje o resultado da verificação chega apenas pelo SDK, no cliente (no Web, por `onSuccess`/`onFailure`). Não há uma rota para o seu backend consultar o resultado de uma sessão.

## POST /api/v1/sessions

Cria uma nova sessão de liveness Identy e retorna o token que o SDK precisa para enviar a captura.

**Endpoint:** `POST https://api.valid.com/vendor-identy/api/v1/sessions`

### Headers

| Header | Valor |
| - | - |
| `x-api-key` | Chave da Plataforma ID — ver [Chaves de API](https://docs-platform.services-valid.com.br/plataforma/chaves-de-api.md) |
| `Content-Type` | `application/json` |

### Body

**clientRequestId** `string (uuid)` *required*

UUID gerado pelo seu backend para cada sessão. Funciona como chave de idempotência: repetir o mesmo valor retorna `409` em vez de criar uma segunda sessão.

**ssid** `string`

Identificador de sessão de dispositivo fornecido pelo SDK. Quando informado, o serviço enriquece a resposta com `deviceScore`, `deviceSignals`, `geolocation` e `ipGeolocation`. Veja [Metadados Complementares](#metadados-complementares).

**platform** `string`

Plataforma de origem da sessão. Valores aceitos: `WEB` ou `APP`. Padrão: `WEB`.

### Resposta 201

**sessionId** `string (uuid)`

ID da sessão criada. Use-o para correlacionar logs e para falhar a sessão, se necessário.

**projectId** `string`

ID do projeto dono da `x-api-key`.

**organizationId** `string`

ID da organização do projeto.

**sessionToken** `string (jwt)`

Token que o SDK usa para enviar a captura. Vale para uma única captura e só é retornado nesta resposta.

**createdAt** `string (iso-8601)`

Data/hora de criação da sessão.

**expiresAt** `string (iso-8601)`

Data/hora de expiração (10 minutos após a criação). Após esse instante a sessão não aceita mais captura.

**deviceScore** `number`

Score de risco do dispositivo. Presente quando o `ssid` é informado e o enriquecimento é bem-sucedido.

**deviceSignals** `object`

Sinais de risco do dispositivo, todos `boolean` e opcionais. Presente quando o `ssid` é informado e o enriquecimento é bem-sucedido. `APP` e `WEB` preenchem conjuntos diferentes — veja a [lista completa](#sinais-do-dispositivo).

**geolocation** `object`

Geolocalização do dispositivo (`latitude`, `longitude`). No Web, só vem preenchida se a sua aplicação já tiver pedido e recebido permissão de localização do usuário **antes** dessa chamada — veja [Metadados Complementares](#metadados-complementares). Opcional.

**ipGeolocation** `object`

Geolocalização derivada do IP (`latitude`, `longitude`). Depende do `ssid`, mas não da permissão de localização. Opcional.

### Códigos de erro

| Status | Quando ocorre |
| - | - |
| `400` | `clientRequestId` ausente ou fora do formato UUID, ou `platform` com valor inválido |
| `401` | Header `x-api-key` ausente ou inválido |
| `409` | Já existe uma sessão com o mesmo `clientRequestId` no projeto |
| `503` | Serviço temporariamente indisponível |

## POST /api/v1/sessions/:sessionId/fail

Encerra explicitamente uma sessão ativa sem captura submetida. Use apenas para problemas **entre o SDK e o seu próprio servidor**, antes da captura começar. Evite chamar depois que o SDK já iniciou a captura: a sessão é encerrada mesmo assim, o que derruba um fluxo que ainda estava em andamento.

**Endpoint:** `POST https://api.valid.com/vendor-identy/api/v1/sessions/:sessionId/fail`

### Headers

| Header | Valor |
| - | - |
| `x-api-key` | Chave da Plataforma ID — ver [Chaves de API](https://docs-platform.services-valid.com.br/plataforma/chaves-de-api.md) |
| `Content-Type` | `application/json` |

### Path params

| Param | Tipo | Descrição |
| - | - | - |
| `sessionId` | UUID | `sessionId` retornado pelo `POST /api/v1/sessions` |

### Body

**reason** `string` *required*

Motivo do encerramento (1 a 500 caracteres). Persistido para auditoria — não inclua dados sensíveis do usuário aqui.

### Resposta 200

**sessionId** `string (uuid)`

ID da sessão finalizada.

**status** `string`

Sempre `"failed"`.

**failureReason** `string`

Eco do `reason` enviado.

**finalizedAt** `string (iso-8601)`

Data/hora em que a sessão foi marcada como falha.

### Códigos de erro

| Status | Quando ocorre |
| - | - |
| `400` | `sessionId` não é UUID ou `reason` ausente/fora do tamanho permitido |
| `401` | `x-api-key` ausente ou inválido |
| `404` | Sessão não encontrada para o projeto |
| `409` | Sessão já está finalizada |

## Metadados Complementares

O `ssid` é um identificador de sessão de dispositivo que o SDK obtém antes da criação da sessão — no Web, ele chega no parâmetro do seu [`onInit`](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao#criando-a-sessão). Quando você o repassa em `POST /api/v1/sessions`, o serviço enriquece a resposta com:

* **`deviceScore`** e **`deviceSignals`** — score e sinais de risco do dispositivo (bot, navegação anônima, emulador, root/jailbreak, proxy etc.).
* **`ipGeolocation`** — localização derivada do IP.
* **`geolocation`** — latitude/longitude do dispositivo. No Web, só quando o usuário já concedeu permissão de localização ao navegador: o SDK **não solicita** essa permissão. Se a sua aplicação quiser esse dado, peça a permissão (via `navigator.geolocation`) **antes** de criar a sessão.

### Sinais do dispositivo

Cada sinal de `deviceSignals` é um `boolean` (`true` = sinal detectado). Um sinal ausente não foi informado para aquela plataforma ou sessão.

| Plataforma | Sinal | Indica |
| - | - | - |
| `WEB` | `bot` | Navegação automatizada (bot) |
| `WEB` | `tor` | Acesso pela rede Tor |
| `WEB` | `incognito` | Janela anônima |
| `WEB` | `browserSpoofed` | Navegador se passando por outro |
| `WEB` | `antiFingerprinting` | Proteção contra identificação do navegador ativa |
| `WEB` | `prvSet` | Sinal `prv_set` da Shield |
| `APP` | `appTampering` | App modificado |
| `APP` | `autoClickerEnabled` | Auto clicker ativo |
| `APP` | `debugging` | App em depuração |
| `APP` | `hooking` | Ferramenta de hooking ativa |
| `APP` | `deviceMasked` | Identidade do dispositivo mascarada |
| `APP` | `emulated` | Emulador |
| `APP` | `jailbroken` | Root (Android) ou jailbreak (iOS) |
| `APP` | `proxy` | Tráfego passando por proxy |
| `APP` | `requestPayloadTampered` | Dados da requisição adulterados |
| `APP` | `clonedApps` | App clonado |
| `APP` | `gpsSpoofers` | App de GPS falso |
| `APP` | `screenSharing` | Compartilhamento de tela ativo |
| `APP` | `vpnSpoofers` | VPN ativa |
| `APP` | `secondaryUser` | Usuário secundário do Android |
| `APP` | `susSdkConn` | Conexão suspeita com o SDK |
| `APP` | `suspiciousFactoryReset` | Reset de fábrica suspeito |
| `APP` | `virtualOs` | Sistema operacional virtual |

> [!NOTE]
>
> **Nem sempre o SDK consegue obter o `ssid`.** Por isso o campo é **opcional**: quando ausente, ou quando o enriquecimento falha, o serviço cria a sessão normalmente, apenas sem esses campos.

## Boas práticas

> **Nunca embuta a x-api-key no cliente**
>
> Mantenha a chave **apenas** no seu backend, idealmente em um Secret Manager. O cliente só deve receber `sessionId` e `sessionToken`.

> **Gere um clientRequestId novo para cada sessão**
>
> Repetir um `clientRequestId` retorna `409`. Gere um UUID novo a cada chamada de criação de sessão — inclusive a cada nova tentativa do usuário.

> **Mantenha os sinais de risco no backend**
>
> `deviceScore`, `deviceSignals` e a geolocalização são para a sua própria análise antifraude. Não os devolva à página ou ao app.

> **Repasse o ssid quando disponível**
>
> Quando o SDK fornecer o `ssid`, inclua-o no `POST /api/v1/sessions` para receber os sinais de risco do dispositivo.

> **Falhe sessões abandonadas explicitamente**
>
> Sessões não finalizadas expiram sozinhas em 10 minutos, mas chamar `/fail` com um `reason` significativo melhora auditoria e investigação de incidentes.

## Próximos passos

> **[Instalação Web](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/instalacao.md)**
>
> Carregue o SDK via uma única tag de script, direto do CDN

> **[Implementação Web](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao.md)**
>
> Inicie a verificação com o token de sessão emitido pelo serviço

> **[Chaves de API](https://docs-platform.services-valid.com.br/plataforma/chaves-de-api.md)**
>
> Gere e gerencie a sua chave da Plataforma ID

> **[Autenticação](https://docs-platform.services-valid.com.br/plataforma/autenticacao-api.md)**
>
> Como o header x-api-key funciona em todas as APIs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.