Inscrição SMS ou TOTP, verificação, provas de uso único e recuperação de acesso na mesma API. A tua aplicação continua a gerir o login principal e as sessões.
curl -X POST 'https://api.kambasms.ao/authenticator/v1/applications/APPLICATION_UUID/subjects/SUBJECT_UUID/enrollments' \
-H 'X-API-Key: YOUR_SERVER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"phone": "+2449XXXXXXXX",
"context_id": "RANDOM_CONTEXT_AT_LEAST_32_CHARACTERS"
}'Exemplo parcial para o servidor. UUIDs, chave e contexto são placeholders; completa o fluxo no guia abaixo.
Uma aplicação local em Node.js demonstra inscrição, segundo fator, códigos de recuperação e troca do número. A chave e as provas ficam no servidor; usa apenas a Sandbox.
node --env-file=.env.local server.cjsReferência local de integração. O login e as sessões em memória são de demonstração; adapta-os ao teu sistema antes de usar em produção.
Kamba Authenticator / TOTP
SMS e TOTP no mesmo serviço. TOTP usa códigos de 6 dígitos que mudam a cada 30 segundos e não consome créditos SMS. Configura o relógio do telemóvel automaticamente.
POST /totp/enrollmentsEnvia context_id aleatório (32–200 caracteres). Apresenta qr_data_url ao utilizador autenticado. A URI e o QR contêm o segredo: não os guardes em logs, analytics ou caches.
POST /totp/enrollments/:id/confirmEnvia code (6 dígitos) e o mesmo context_id. Só ativa após confirmação. Guarda factor_id, sem guardar o segredo no teu cliente.
POST /totp/challengesApós o login principal, envia factor_id, novo context_id e purpose: login. Nenhum SMS é enviado.
POST /totp/challenges/:id/checkEnvia code e mesmo contexto. Recebe proof temporária; ainda não cria uma sessão.
POST /proofs/consumeEnvia proof e mesmo contexto. Só autoriza depois de authorized: true. Mantém o login principal e as sessões no teu sistema.
Prefixo: /authenticator/v1/applications/:app/subjects/:subject. Todas as chamadas usam X-API-Key no servidor. A chave API nunca vai para o navegador.
Adicionar TOTP quando já existe um fator exige proof de login fresca e o mesmo contexto. Para substituir um TOTP perdido: /recovery/check, depois /totp/enrollments com recovery: true, proof e o mesmo contexto. O antigo permanece ativo até confirmares o novo. Depois revoga sessões e gera novos códigos de recuperação.
Códigos de recuperação: inicia /totp/challenges com purpose: recovery_codes, valida e envia a proof para /recovery-codes. As provas são separadas por finalidade. Cancelar: /totp/challenges/:id/cancel com context_id.
Desafio: 5 minutos, até 5 tentativas; prova: 2 minutos e uso único. Cada código TOTP aceite só pode ser usado uma vez; aguarda o próximo código para uma nova operação. A tolerância de relógio é de um intervalo antes/depois.
API / 2FA
Quatro percursos, do primeiro fator SMS à recuperação. Segue os passos pela ordem indicada.
01
Confirma a posse do número antes de criar o fator ativo.
/applicationsEnvia name e guarda application_id.
/applications/:app/subjectsEnvia external_subject_id opaco; guarda subject_id.
/enrollmentsEnvia phone e context_id aleatório; guarda enrollment_id.
/enrollments/:id/confirmEnvia code e o mesmo context_id; guarda factor_id.
02
Começa após o login principal no teu sistema.
/challengesEnvia factor_id e novo context_id.
/challenges/:id/checkEnvia code e o mesmo contexto; recebe proof temporária.
/proofs/consumeEnvia proof e context_id no servidor. Só cria sessão após authorized: true.
03
Exige uma nova confirmação do fator SMS ativo.
/challengesEnvia factor_id, context_id e purpose: recovery_codes.
/challenges/:id/checkEnvia code, mesmo contexto e purpose: recovery_codes.
/recovery-codesEnvia proof e mesmo contexto. Guarda os dez códigos: apresentados uma vez; regenerar invalida os antigos.
04
O número antigo permanece ativo até confirmares o novo.
/recovery/checkEnvia code e novo context_id. A proof recovery não permite login.
/recovery/replacementEnvia proof, phone e mesmo context_id; recebe enrollment_id.
/enrollments/:id/confirmConfirma o SMS do novo destino. Revoga as sessões no teu sistema e gera novo lote de recuperação.