Skip to main content
O serviço de sessões FaceTec autoriza o seu projeto e devolve ao seu cliente o token que o LivenessFacetecSDK precisa para abrir a captura. Sem essa chamada, o SDK não consegue inicializar. A base URL de produção é https://api.valid.com/facetec-vendor e a rota fica abaixo de /api/v2. A autenticação usa a sua x-api-key, gerada na Plataforma ID — veja Chaves de API.
A URL do seu backend que faz essas chamadas precisa ser liberada pela equipe da Valid antes da primeira chamada. Sem essa liberação, as chamadas a este serviço são rejeitadas mesmo com uma x-api-key válida. Envie a URL (produção e homologação, se houver) à equipe da Valid antes de integrar.
O domínio (Web), Package Name (Android) ou Bundle Identifier (iOS) do seu app também precisam ser liberados na licença FaceTec — veja os pré-requisitos de instalação Web, Android e iOS.

​
Por que essa chamada existe

O LivenessFacetecSDK é apenas um cliente: quem cria a sessão é o seu backend. Na v10, ao contrário da v9, o SDK Web se comunica diretamente com o serviço FaceTec para todo o resto do fluxo (inicialização do motor, captura, status) usando o sessionToken emitido nesta chamada — você não precisa implementar nem fazer proxy dessas outras chamadas.
  • POST /api/v2/sessions — cria a sessão de liveness e devolve o sessionToken que o SDK usa para todo o resto do fluxo.
  • POST /api/v2/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 no painel. Evite chamar depois que o SDK já foi inicializado: a sessão é marcada como encerrada mesmo assim, o que pode interromper uma captura em andamento.
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 e libera acesso à cobrança e às credenciais FaceTec. Embuti-la no binário Android, no IPA ou no bundle JS de uma SPA é equivalente a publicar a chave no repositório — 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 opcionalmente o ssid que o SDK Web obtém durante a inicialização — veja Metadados Complementares.
2

Seu backend chama POST /api/v2/sessions

Servidor para servidor, com o header x-api-key. O serviço retorna sessionId e sessionToken.
3

Seu backend devolve os tokens ao cliente

Envie ao cliente apenas o que ele precisa: sessionId, sessionToken e expiresAt.
4

Cliente inicializa o Liveness com esses tokens

O LivenessFacetecSDK consome os tokens e abre a captura. Veja Implementação Web.
5

Se a captura falhar, tente novamente

Não existe retry dentro da mesma sessão: se a captura falhar, o app simplesmente chama o SDK de novo — o que cria automaticamente uma nova sessão.
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/v2/sessions/:sessionId/fail para marcar a sessão como falha — o motivo fica registrado para auditoria no painel. Chame somente nessa janela: se disparado depois que o SDK já foi inicializado, a chamada continua funcionando e encerra a sessão do mesmo jeito, mas como o SDK pode já estar em captura nesse ponto, isso derruba um fluxo que ainda estava em andamento. Sessões não finalizadas também expiram sozinhas por TTL.

​
POST /api/v2/sessions

Cria uma nova sessão de liveness FaceTec e retorna o token que o SDK precisa para inicializar a captura. Endpoint: POST https://api.valid.com/facetec-vendor/api/v2/sessions
Essa resposta também pode trazer sinais antifraude. Quando você informa o ssid, o serviço retorna adicionalmente deviceSignals (sinais de risco do dispositivo) e geolocation/ipGeolocation (localização aproximada) — veja Metadados Complementares.

​
Headers

​
Body

​
string (uuid)
required
UUID gerado pelo seu backend para esta tentativa. Funciona como chave de idempotência: reenvios com o mesmo (projeto, clientRequestId) retornam a mesma sessão em vez de criar uma nova.
​
string
Identificador de sessão de dispositivo obtido pelo SDK Web durante a inicialização. Quando informado, o serviço enriquece a resposta com deviceSignals, geolocation e ipGeolocation. Veja Metadados Complementares.
​
string
Plataforma de origem da chamada. Valores aceitos: APP ou WEB.

​
Resposta 201

​
string (uuid)
ID da sessão criada. Use-o no SDK e para correlacionar logs.
​
string (jwt)
Token emitido pelo serviço. O SDK Web utiliza este token para todo o restante do fluxo de captura — você não precisa repassá-lo para mais nenhuma chamada própria.
​
string (iso-8601)
Data/hora de criação da sessão.
​
string (iso-8601)
Data/hora de expiração. Após esse instante a sessão não aceita mais captura.
​
string
Texto de consentimento / aviso legal. Exiba ao usuário antes de iniciar a captura.
​
object
Sinais de risco do dispositivo, obtidos via Shield. Presente quando o ssid é informado e o enriquecimento é bem-sucedido. O conjunto de flags varia por plataforma (ex.: appTampering, hooking, emulated, jailbroken, proxy, clonedApps para APP; bot, tor, incognito, browserSpoofed para WEB).
​
object
Geolocalização do dispositivo (latitude, longitude), obtida via GPS/navegador. 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 da requisição (latitude, longitude). Também depende do ssid, mas não depende de permissão de localização do usuário — só do enriquecimento via ssid ter sido bem-sucedido. Opcional.

​
Códigos de erro

​
POST /api/v2/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 — cancelamento do usuário antes de iniciar, falha de validação no seu backend, timeout do front, etc. O motivo enviado fica registrado e visível para auditoria no painel. Evite chamar depois que o SDK já foi inicializado: a chamada continua funcionando e encerra a sessão do mesmo jeito, mas como o SDK pode já estar em captura nesse ponto, isso derruba um fluxo que ainda estava em andamento — o backend passa a considerar a sessão finalizada enquanto o SDK ainda está processando. É a mesma operação da v9, só na rota /api/v2. Endpoint: POST https://api.valid.com/facetec-vendor/api/v2/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 LivenessFacetecSDK Web obtém durante a inicialização, antes de qualquer chamada ao serviço de sessão. Quando você o repassa em POST /api/v2/sessions, o serviço enriquece a resposta com dois tipos de dado adicional:
  • deviceSignals — sinais de risco do dispositivo (emulador, root/jailbreak, proxy, bot, etc.), sempre que o ssid é aceito.
  • geolocation — latitude/longitude do dispositivo, mas só quando o usuário já concedeu permissão de localização ao navegador. O SDK não solicita essa permissão por conta própria: se a sua aplicação quiser esse dado, ela precisa pedir a permissão de localização ao usuário (via navigator.geolocation do próprio navegador) em algum momento antes de criar a sessão — por exemplo, ao carregar a página. Sem esse pedido prévio feito pela sua aplicação, o campo simplesmente não vem na resposta.
Nem sempre o SDK consegue obter o ssid. A coleta depende de conectividade no momento da inicialização e do ambiente de execução. Por isso o campo é opcional: quando ausente, o serviço cria a sessão normalmente, apenas sem nenhum dos três campos de enriquecimento (deviceSignals, geolocation, ipGeolocation).

​
Boas práticas

Mesmo ofuscada, qualquer chave embarcada no bundle JS pode ser extraída com ferramentas comuns (DevTools). Mantenha a chave apenas no seu backend, idealmente em um Secret Manager. O cliente só deve receber sessionId e sessionToken.
Gere o UUID no início do fluxo e reutilize-o em retries de rede do seu backend. Reenvios com o mesmo (projeto, clientRequestId) retornam a mesma sessão, evitando duplicar consumo e tokens.
Quando o SDK Web conseguir obter o ssid, repasse-o ao seu backend e inclua-o no POST /api/v2/sessions. Você recebe deviceSignals, geolocation e ipGeolocation em troca — úteis para regras antifraude.
Não existe mais maxAttempts nem retry dentro da mesma sessão. Para tentar de novo após uma falha de captura, basta chamar o SDK Web mais uma vez — ele cria uma nova sessão automaticamente.
Sessões não finalizadas expiram sozinhas por TTL, mas chamar /fail com um reason significativo melhora auditoria, reconciliação de métricas 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

Inicialize o SDK 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