LivenessFacetecSDK precisa para abrir a UI nativa. Sem essa chamada, o SDK não consegue inicializar a captura.
A base URL de produção é https://facetec.hub-liveness-service.app e todas as rotas ficam abaixo de /api/v1. A autenticação segue o padrão da Plataforma ID via header x-api-key — veja Chaves de API
Por que essas chamadas existem
OLivenessFacetecSDK é apenas um cliente: quem cria a sessão, gerencia o ciclo de vida e fala com o FaceTec é o serviço. O fluxo completo de uma captura passa por duas integrações server-side que você precisa implementar:
POST /api/v1/sessions— cria a sessão de liveness e devolvesessionToken+facetecSessionToken. Sem esses valores o SDK não consegue inicializar a UI do FaceTec.POST /api/v1/sessions/:sessionId/fail— encerra uma sessão ativa quando o fluxo é abortado fora do SDK (usuário cancela na sua tela, validação de negócio rejeita antes da captura, timeout do front, etc.). Importante para reconciliação e auditoria.
Fluxo recomendado
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
visitorId e eventId que o SDK já obteve durante a inicialização — veja Metadados Complementares.Seu backend chama POST /api/v1/sessions
Servidor para servidor, com o header
x-api-key. A Plataforma ID retorna sessionId, sessionToken, facetecSessionToken e metadados complementares.Seu backend devolve os tokens ao cliente
Envie ao cliente apenas o que ele precisa:
sessionId, sessionToken, facetecSessionToken e expiresAt.Cliente inicializa o Liveness com esses tokens
O
LivenessFacetecSDK consome os tokens e abre a UI nativa do FaceTec. Veja Implementação Android ou Implementação iOS.POST /api/v1/sessions
Cria uma nova sessão de liveness FaceTec e retorna os tokens que o SDK precisa para inicializar a captura. Endpoint:POST https://facetec.hub-liveness-service.app/api/v1/sessions
Headers
| Header | Valor |
|---|---|
x-api-key | Chave da Plataforma ID — ver Chaves de API |
Content-Type | application/json |
Body
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.Identificador de dispositivo obtido pelo SDK durante a inicialização.
Identificador do evento de inicialização do SDK, usado para correlacionar sinais de risco do dispositivo. Quando informado, o serviço enriquece a resposta com
deviceSignals e geolocation. Veja Metadados Complementares.Número máximo de capturas biométricas permitidas na sessão. Quando uma captura falha e ainda há tentativas disponíveis, o FaceTec exibe a tela de retry automaticamente sem criar nova sessão. Mínimo: 1 · Máximo: 5 · Default: 3
Resposta 201
ID da sessão criada. Use-o no SDK e em chamadas subsequentes ao serviço.
JWT HS256 emitido pelo serviço (TTL de 600s). O SDK utiliza este token ao submeter a captura.
Token do FaceTec necessário para inicializar a UI nativa da captura.
Data/hora de criação da sessão.
Data/hora de expiração. Após esse instante a sessão é marcada como
expired e não aceita mais captura.Texto de consentimento / aviso legal. Exiba ao usuário antes de iniciar a captura.
Sinais de risco do dispositivo. Presente quando o
eventId é informado e o enriquecimento é bem-sucedido. Inclui suspectScore, flags como emulator, simulator, root, jailbroken, frida, mitm, tampering, bot, antiDetectBrowser, developerTools, locationSpoofing, incognito, clonedApp, factoryReset, replayed, tor, blocklist, emailSpam, além de vpnConfidence (low | medium | high | null) e proxyType (residential | data_center | null).Geolocalização derivada do
visitorId: latitude, longitude, city, region, country e timezone. Também opcional.Códigos de erro
| Status | Quando ocorre |
|---|---|
400 | clientRequestId ausente ou fora do formato UUID |
401 | Header x-api-key ausente ou inválido |
403 | Chave válida, mas o projeto não tem o produto Liveness habilitado |
500 | Falha ao mintar o token FaceTec via Apigee |
POST /api/v1/sessions/:sessionId/fail
Encerra explicitamente uma sessão ativa sem captura submetida. Use sempre que o fluxo for abortado fora do SDK — cancelamento do usuário antes de iniciar, falha de validação no seu backend, timeout do front, etc. Endpoint:POST https://facetec.hub-liveness-service.app/api/v1/sessions/:sessionId/fail
Headers
| Header | Valor |
|---|---|
x-api-key | Chave da Plataforma ID — ver Chaves de API |
Content-Type | application/json |
Path params
| Param | Tipo | Descrição |
|---|---|---|
sessionId | UUID | sessionId retornado pelo POST /api/v1/sessions |
Body
Motivo do encerramento (1 a 500 caracteres). Persistido para auditoria — não inclua dados sensíveis do usuário aqui.
Resposta 200
ID da sessão finalizada.
Sempre
"failed".Eco do
reason enviado.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 (completed, failed ou expired) |
Metadados Complementares
OeventId é um identificador do evento que o LivenessFacetecSDK obtém durante a inicialização, antes de qualquer chamada ao serviço de sessão. Quando você o repassa em POST /api/v1/sessions, o serviço enriquece a resposta com dois objetos opcionais:
deviceSignals— flags de risco do dispositivo (emulador, root, MITM, bot, VPN, etc.).geolocation— localização aproximada derivada do dispositivo.
Nem sempre o SDK consegue obter o
eventId. A coleta depende de conectividade no momento do init, das permissões do dispositivo, das configurações de privacidade do usuário e do ambiente de execução — alguns simuladores e dispositivos com privacidade agressiva bloqueiam a coleta. Por isso o campo é opcional: quando ausente, o serviço cria a sessão normalmente, apenas sem o enriquecimento de deviceSignals e geolocation.eventId ao seu backend no mesmo request em que pede a sessão. O SDK expõe esse valor depois que init retorna com sucesso — consulte a documentação de implementação da sua plataforma para detalhes do acesso.
Boas práticas
Nunca embuta a x-api-key no cliente
Nunca embuta a x-api-key no cliente
Mesmo ofuscada, qualquer chave embarcada no binário Android/iOS ou no bundle JS pode ser extraída com ferramentas comuns (
jadx, Hopper, DevTools). Mantenha a chave apenas no seu backend, idealmente em um Secret Manager. O cliente só deve receber sessionToken e facetecSessionToken.Use clientRequestId para idempotência
Use clientRequestId para idempotência
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.Falhe sessões abandonadas explicitamente
Falhe sessões abandonadas explicitamente
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.Repasse o eventId quando disponível
Repasse o eventId quando disponível
Quando o SDK conseguir obter o
eventId, repasse-o ao seu backend e inclua-o no POST /api/v1/sessions. Você recebe deviceSignals e geolocation em troca — úteis para regras antifraude.Próximos passos
Implementação Android
Inicialize o SDK com o token de sessão emitido pelo serviço
Implementação iOS
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