Cifragem de fatores e provas assinadas
Números de telefone e segredos TOTP são cifrados com AES-256-GCM (chaves versionadas v1) e códigos OTP são verificados por HMAC-SHA256 sem guardar texto limpo.
Disponível · SMS + TOTP · AES-256-GCM
KambaSMS / Kamba Authenticator
Um fluxo completo para o segundo fator.
Inscrição SMS ou TOTP, verificação, provas de uso único e recuperação de acesso na mesma API. Cifragem AES-256-GCM, HMAC-SHA256 e rastreio DLR com [OTP ocultado] incluídos de raiz.
POST /authenticator/v1/.../enrollments2FA / PROOF
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"
}'Registar o fator SMS
01 / Fluxo do produto
Três etapas: inscrição, desafio e recuperação.
Antes de integrar
- Usa uma chave autorizada com scope authenticator no backend do teu sistema.
- Testa primeiro na Sandbox: o código 123456 não envia SMS nem desconta saldo.
- A aceitação do SMS pelo fornecedor não comprova entrega nem autenticação. A autenticação exige verificar o código e consumir a prova na tua aplicação.
- Em live, cada SMS segue a reserva e o débito de créditos com registo DLR [OTP ocultado]. Gerar ou verificar códigos de recuperação não envia SMS.
- Contextos devem ser aleatórios (mínimo 32 caracteres) e ligados à operação do utilizador. Não uses exemplos fixos em produção.
- Após recuperação, revoga as sessões no teu sistema e gera novos códigos.
Kamba Authenticator / TOTP
Segundo fator com uma aplicação autenticadora.
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.
1. Registar TOTP
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.
2. Confirmar ativação
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.
3. Iniciar segundo fator
POST /totp/challengesApós o login principal, envia factor_id, novo context_id e purpose: login. Nenhum SMS é enviado.
4. Validar código
POST /totp/challenges/:id/checkEnvia code e mesmo contexto. Recebe proof temporária; ainda não cria uma sessão.
5. Concluir no servidor
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.
02 / Segurança Criptográfica e Rastreio
Segundo fator isolado, cifrado e auditável.
Provas criptográficas de uso único
Cada verificação 2FA devolve um proof_token vinculado ao context_id da operação. O teu backend consome a prova uma única vez antes de autorizar a sessão.
Rastreio de entrega e redação automática
Os desafios SMS ficam ligados ao histórico de entrega das operadoras angolanas com a mensagem gravada como [OTP ocultado] para auditoria sem exposição do código.
10 códigos de recuperação sem custo SMS
A geração e validação de códigos de recuperação é puramente criptográfica e só substitui o fator antigo depois de o novo número ser confirmado.
Próximo passo
Explora o guia completo ou testa já na Sandbox.
Consulta a sequência completa de endpoints ou descarrega o projeto Node.js de referência em /docs/authenticator.
Antes de integrar
Kamba Authenticator: o que precisas de saber.
Consulta os requisitos, as regras de consumo e o âmbito do serviço antes de ativar a integração. A documentação contém os contratos completos da API.
Como tratar um limite de pedidos?
Se receberes HTTP 429, respeita o cabeçalho Retry-After quando estiver presente. Evita repetir em ciclo. Os limites de pedidos, o saldo e as quotas de OTP são controles distintos. Um timeout de envio pode ter resultado desconhecido: consulta a operação original antes de tentar um novo envio.
A página de status garante a entrega?
A página apresenta incidentes reportados manualmente. A ausência de incidentes não comprova disponibilidade ou entrega. Para SMS, aceite pelo fornecedor, entregue segundo DLR e código verificado são estados distintos; no sandbox não existe entrega real.
O que preciso para começar?
A tua aplicação gere a conta, o primeiro fator e a sessão. O Authenticator gere a inscrição do segundo fator, desafios e provas. Integra no backend, com contexto aleatório por operação: inscrição, confirmação, desafio, verificação e consumo da prova antes de autorizar a sessão.
Como funciona o consumo?
O SMS padrão de inscrição ou desafio real consome um crédito por envio. TOTP gera códigos na aplicação autenticadora e não envia SMS. Sandbox não debita saldo. A aplicação deve tratar falhas e resultados incertos antes de repetir um pedido pago.
Quais são os limites e o âmbito?
SMS e TOTP têm fluxos próprios de inscrição, confirmação e recuperação. Um QR TOTP só deve ser mostrado ao titular durante a configuração; contém um segredo. O acesso live depende de ativação e configuração para a conta. A demonstração ou o código de exemplo não confirmam essa ativação.
O que devo verificar se algo falhar?
Verificar o código e consumir a prova são etapas diferentes. Só autorizes a operação após consumo válido. Não reutilizes contexto, prova ou código para outra operação. Prevê recuperação e substituição do fator antes de exigir 2FA aos utilizadores; nunca registes OTP, QR, segredo ou prova nos logs.
Precisas de ajuda? Indica o produto, horário, ID do pedido e uma descrição do problema. Não partilhes chaves API, códigos OTP ou conteúdo pessoal das mensagens. Para capacidade ou compromissos específicos da conta, confirma as condições com o suporte.