API v1
Verificar código
/v1/send/{id}/verifyCompara o código informado com o código do envio. O resultado de autenticação está em valid, não no status HTTP.
Nesta página
Requisição
Envie Authorization, Content-Type e um objeto JSON com code como string. No modo live, use o código recebido pela pessoa. O exemplo usa o código padrão de teste.
curl "https://api.aut2fa.com/v1/send/$SEND_ID/verify" \
-H "Authorization: Bearer $AUT2FA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code":"000000"}'Vincule o ID à sessão atual antes de fazer a chamada. O estado de entrega não é uma condição para chamar a verificação.
Resposta 200: código correto
{
"valid": true,
"verification": "verified",
"attempts_left": 0
}| Campo | Significado |
|---|---|
valid | true somente na chamada que verifica o código com sucesso. |
verification | Estado após a chamada: pending, verified, expired ou locked. |
attempts_left | Tentativas restantes depois de um erro. É 0 quando a verificação encerrou, inclusive no sucesso. |
Conclua a operação protegida somente quando valid === true. O código é de uso único: repetir uma verificação bem-sucedida retorna valid: false e verification: verified.
Código incorreto e estados encerrados
| Situação | valid | verification | attempts_left |
|---|---|---|---|
| Primeiro erro, antes de expirar | false | pending | 4 |
| Quinto erro | false | locked | 0 |
| Prazo encerrado | false | expired | 0 |
| Código já usado | false | verified | 0 |
Todos esses resultados retornam HTTP 200. Cinco códigos incorretos bloqueiam o envio. Se o estado for expired ou locked, ofereça um novo envio com outro ID e outra chave de idempotência.
Evite retentativas automáticas da verificação. Se o resultado ficar indeterminado após timeout ou erro de rede, consulte o status para diagnosticar. Retome a autenticação somente se o seu próprio backend já registrou valid: true para essa sessão; se não conseguir recuperar esse resultado, inicie outro desafio com novo ID e outra chave de idempotência.
Prazo de validade
O prazo padrão da configuração é 10 minutos, mas pode mudar. Sempre use o expires_at do envio, em vez de fixar uma duração na integração.
Um envio verificado permanece verified após o prazo; apenas códigos ainda pendentes passam a expired.
Erros HTTP
Corpo JSON inválido retorna 422 com invalid_json. Código incorreto retorna o resultado HTTP 200 descrito acima.
ID inexistente ou de outra conta retorna 404 com send_not_found. Chave ausente ou inválida retorna 401.