Token JWT

Alguns cenários não permitem usar a chave de API diretamente. É o caso dos SDKs de liveness, que rodam no aplicativo ou no navegador do usuário final — embutir a chave de API ali a exporia a qualquer pessoa que inspecionasse o aplicativo.

Para esses casos, o seu backend chama este endpoint com a chave de API e recebe em troca um token JWT de curta duração, que pode ser entregue com segurança ao dispositivo do usuário. O token carrega as mesmas permissões da chave que o gerou e expira sozinho.

Este endpoint não realiza nenhuma análise: ele apenas emite o token.

🚧 Atenção!

A chamada a este endpoint deve partir sempre do seu backend. Nunca coloque a chave de API no aplicativo, no front-end ou em qualquer lugar que o usuário final possa inspecionar.

Request

POST /auth-jwt

Este endpoint não é versionado: a chamada é sempre /auth-jwt, sem versão no caminho.

Headers

Content-Type: application/json
Authorization: ApiKey <sua-chave-de-api>

Este é o único endpoint da documentação que não aceita o token JWT no lugar da chave de API — é ele que emite o token.

Parâmetros

Todos os campos do corpo são opcionais. O corpo pode ser um objeto vazio, ou pode ser omitido.

Parâmetro	Descrição	Obrigatório
federalRevenueNumber	CPF a vincular ao token. Quando enviado, é validado; um CPF inválido faz a requisição falhar. Pode ser enviado com ou sem máscara.	Não
ttl	Tempo de vida do token. String com a unidade de tempo: "15m", "1h", "30s", "7d". Sem ele, vale o padrão do nosso emissor de tokens — hoje, 15 minutos.	Não

‼️ O ttl precisa ser uma string com a unidade

Enviar "ttl": 900 (número) faz a emissão do token falhar com 500. Envie "ttl": "15m". E, mesmo em string, o valor precisa trazer a unidade: "900" sem unidade é lido como 900 milissegundos, não 900 segundos.

Qualquer outro campo enviado no corpo é aceito e viaja dentro do token, mas não altera as permissões concedidas: elas são sempre as da chave de API usada na chamada.

Exemplo Request

curl -i -X POST 'https://api-homolog.nxcd.app/auth-jwt' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --data '{ "federalRevenueNumber": "12345678909", "ttl": "15m" }'

Response

Campo	Descrição	Tipo
accessToken	O token JWT assinado, a ser usado pelo SDK.	String

A resposta deste endpoint não usa o envelope id / version / data / metadata dos endpoints de análise. O identificador da requisição continua disponível no header Nextid-ReqId.

Exemplos JSON

Status Code: 200

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY1MGUxZDJiM2M0ZDVlNmY3ODkwYWJjZCJ9.ASSINATURA_AQUI"
}

Como usar o token

Onde a documentação pede Authorization: ApiKey <chave>, o token JWT entra assim:

Authorization: Bearer <accessToken>

A API decide qual forma usar pelo conteúdo do header Authorization: se ele contém Bearer, o token é validado como JWT; caso contrário, o valor é tratado como chave de API.

Todos os endpoints desta documentação aceitam as duas formas — chave de API ou token JWT. A única exceção é o próprio POST /auth-jwt, que exige a chave de API.

TIP

As permissões do token são as da chave que o emitiu. Se a chave não tem acesso a um produto, o token também não terá, e a resposta será 401.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ausente ou inválida, ou sem a permissão de emissão de token.
422 Unprocessable Entity	O federalRevenueNumber foi enviado, mas não passa na validação do dígito verificador.
500 Internal Server Error	Falha na emissão do token. A causa mais comum de erro evitável aqui é o ttl enviado como número em vez de string.

Exemplo de resposta com CPF inválido:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid Federal Revenue Number"
  }
}

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Próximo passo

Com o token em mãos, siga para o Fluxo de Liveness.