Autenticação

A API de KYC usa o grant client-credentials do OAuth 2.0 (RFC 6749 §4.4). Seu backend troca um client_id e um client_secret por um token Bearer de curta duração e, em seguida, apresenta esse token em cada chamada /v1/*.

As credenciais são exclusivamente server-side. Nunca envie um client_secret — ou um token de acesso — para um navegador ou aplicativo móvel. Seus clientes interagem com o widget, nunca com a API.

Solicitar um Token

Endpoint: POST /oauth/token
Content-Type: application/x-www-form-urlencoded

curl --request POST \
  --url https://{FQDN}/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=$KYC_CLIENT_ID \
  --data client_secret=$KYC_CLIENT_SECRET

As credenciais também podem ser enviadas como autenticação HTTP Basic (client_secret_basic) em vez de no corpo:

curl --request POST \
  --url https://{FQDN}/oauth/token \
  --user "$KYC_CLIENT_ID:$KYC_CLIENT_SECRET" \
  --data grant_type=client_credentials

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "sessions verifications"
}

grant_type deve ser client_credentials — é o único grant que este endpoint aceita.

Scopes

Cada endpoint exige um scope específico. Os tokens são emitidos com os scopes concedidos ao seu client; solicite um conjunto mais restrito com o parâmetro opcional scope quando um componente do seu sistema precisar de apenas um deles.

Scope	Concede acesso a
`sessions`	`POST /v1/sessions`, `GET /v1/sessions/{session_id}`
`verifications`	`POST /v1/verifications`

--data scope=sessions

Solicitar um scope desconhecido é rejeitado, em vez de ignorado silenciosamente. Um token que não possui o scope exigido por um endpoint retorna 403, e não 401 — o token é válido, apenas não está autorizado para aquela chamada.

Usando o Token

Apresente o token como uma credencial Bearer:

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"user_ref": "user-123"}'

O validador de formato de número de documento é a única exceção — POST /v1/validators/document-number é uma verificação de formato sem estado e não precisa de token.

Tempo de Vida e Renovação do Token

Os tokens são JWTs assinados com RS256 e expiram — expires_in informa quando, em segundos. Armazene o token em cache e renove-o antes da expiração; não solicite um novo token a cada chamada de API e não faça hardcode de um token em lugar nenhum.

Um client robusto:

Armazena o token em memória junto com seu timestamp de expiração.
Renova quando o tempo de vida restante cai abaixo de uma pequena margem (30-60 segundos).
Tenta novamente uma vez ao receber 401, caso o token tenha expirado entre a verificação e a chamada.

Respostas de Erro

Os erros do endpoint de token seguem a RFC 6749 §5.2 — um código error com um error_description legível por humanos:

Status	`error`	Causa
`400`	`unsupported_grant_type`	`grant_type` estava ausente ou não era `client_credentials`
`400`	`invalid_scope`	O `scope` solicitado contém um valor desconhecido
`401`	`invalid_client`	Credenciais de client ausentes, desconhecidas ou incorretas. A resposta traz um challenge `WWW-Authenticate: Basic`

{
  "error": "invalid_client",
  "error_description": "Missing client credentials"
}

Erros em chamadas /v1/*:

Status	Causa	Como corrigir
`401`	Sem o header `Authorization: Bearer`	Envie o header; obtenha um token em `POST /oauth/token`
`401`	Token expirado	Renove o token e tente novamente
`401`	Token inválido ou não verificável	Confirme que está usando o token exatamente como recebido e no ambiente correspondente
`403`	O token é válido, mas não possui o scope do endpoint	Solicite um token com o scope necessário

A resposta 403 inclui WWW-Authenticate: Bearer error="insufficient_scope" indicando o scope que era exigido.

Isolamento de Ambientes

O sandbox e a produção emitem credenciais separadas, e cada token é válido apenas no ambiente que o emitiu. As sessões são estritamente restritas ao tenant que as criou: um token nunca pode ler a sessão de outro tenant, e uma requisição para uma delas retorna 404.

Rotação do Seu Secret

Os client secrets são rotacionados pela Inyo mediante solicitação — entre em contato com seu representante Inyo em vez de tentar a rotação pela API. Rotacione imediatamente se um secret possa ter sido exposto.

Próximos Passos

Primeiros Passos — execute uma verificação completa com seu novo token
Sessões de Verificação — todos os campos de POST /v1/sessions