Skip to main content
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.
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.

​
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.
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.
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, Android ou iOS.
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.
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

​
Body

​
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.
​
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.
​
string
Plataforma de origem da sessão. Valores aceitos: WEB ou APP. Padrão: WEB.

​
Resposta 201

​
string (uuid)
ID da sessão criada. Use-o para correlacionar logs e para falhar a sessão, se necessário.
​
string
ID do projeto dono da x-api-key.
​
string
ID da organização do projeto.
​
string (jwt)
Token que o SDK usa para enviar a captura. Vale para uma única captura e só é retornado nesta resposta.
​
string (iso-8601)
Data/hora de criação da sessão.
​
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.
​
number
Score de risco do dispositivo. Presente quando o ssid é informado e o enriquecimento é bem-sucedido.
​
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.
​
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. Opcional.
​
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

​
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

​
Path params

​
Body

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

​
Resposta 200

​
string (uuid)
ID da sessão finalizada.
​
string
Sempre "failed".
​
string
Eco do reason enviado.
​
string (iso-8601)
Data/hora em que a sessão foi marcada como falha.

​
Códigos de erro

​
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. 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.
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

Mantenha a chave apenas no seu backend, idealmente em um Secret Manager. O cliente só deve receber sessionId e sessionToken.
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.
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.
Quando o SDK fornecer o ssid, inclua-o no POST /api/v1/sessions para receber os sinais de risco do dispositivo.
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

Carregue o SDK via uma única tag de script, direto do CDN

Implementação Web

Inicie a verificação com o token de sessão emitido pelo serviço

Chaves de API

Gere e gerencie a sua chave da Plataforma ID

Autenticação

Como o header x-api-key funciona em todas as APIs