Gera um segredo TOTP temporário para o usuário autenticado

Primeiro passo do cadastro de um autenticador TOTP (Google Authenticator, Authy, 1Password etc).

Existe para permitir o cadastro sem QR Code, útil quando quem conduz o fluxo é o próprio aplicativo do celular: em vez de exibir um QR para ser escaneado por um segundo aparelho, o app recebe o segredo, registra o autenticador localmente e devolve o código.

Quando chamar

Só depois da migração concluída. Este endpoint opera sobre um usuário já existente e autenticado, identificado pelo claim sub do access token. Durante o /authorize que dispara a migração o usuário ainda não foi persistido — ele só é gravado no banco no último passo do /register/migration —, então não existe sub, não existe token e esta API não tem sobre quem operar. Chamá-la antes disso responde 401. Não há como cadastrar o TOTP no meio da migração por aqui.

A ordem é:

1. conclua a migração em /register/migration, até o usuário estar logado;
2. faça o /authorize e troque o code por tokens;
3. cadastre o TOTP com estes dois endpoints.

A migração termina com e-mail e telefone comprovados, então a sessão já sai no nível urn:iugu:grant_scopes:config: o passo 2 devolve um token no nível necessário sem pedir nenhuma verificação adicional, desde que aconteça dentro do max_age daquele nível (10 minutos por padrão). Passado esse prazo, o provedor pede uma verificação nova.

Pré-requisito: o cliente não pode exigir TOTP

Por padrão a própria migração cadastra o TOTP, exibindo um QR Code no fim do fluxo. Nesse caso o usuário já sai da migração com o fator configurado e esta API responde 409.

O cadastro via API existe para o cenário em que o QR Code não serve — tipicamente um app mobile conduzindo a migração no mesmo aparelho que seria usado para escanear. Para habilitá-lo, o cliente precisa não exigir totp na sua configuração (auth_methods.totp.required: false). Isso tem dois efeitos, ambos necessários:

• a migração pula o passo de TOTP e termina com e-mail e telefone;
• o /authorize devolve um code em vez de mandar o usuário para a tela de configuração de métodos, que é o que aconteceria enquanto houver método obrigatório pendente.

O minimum_auth_methods do cliente também precisa caber no que a migração entrega (2 métodos), pelo mesmo motivo. A exigência de TOTP continua valendo normalmente para os demais clientes, e é satisfeita assim que o cadastro via API terminar.

A configuração de cliente substitui o documento inteiro, não faz merge com o padrão: o config do cliente precisa ser uma cópia completa com as chaves ajustadas.

O que este endpoint faz

Gera um segredo em Base32, guarda-o temporariamente vinculado ao usuário do token e devolve tudo que o autenticador precisa, incluindo a URI de provisionamento pronta (provisioning_uri) no formato padrão otpauth://. Não é preciso montá-la manualmente nem renderizar um QR Code: basta entregá-la ao autenticador (por deep link, ou importando o segredo direto no app).

O segredo ainda não está ativo na conta. A vinculação só acontece quando o código é confirmado em POST /api/auth_methods/totp/new. Guarde o id retornado: ele é obrigatório na confirmação e só pode ser confirmado pelo mesmo usuário que o gerou. Se o ttl expirar antes, chame este endpoint novamente para obter um novo segredo.