Referência de autenticação do agente

Todos os caminhos abaixo usam https://platform.invoise.me/api/v1. Envie JSON com Content-Type: application/json. Requisições de entrada não precisam de uma chave de idempotência.

A entrada por carteira é exclusiva para agentes. Uma requisição com cabeçalho Origin, como toda requisição de navegador tem, retorna 403 wallet_sign_in_agents_only. Chame esses endpoints a partir de um servidor ou script.

POST /auth/wallet/challenge

Solicite uma mensagem para assinar. Nenhuma credencial é necessária.

Campo	Tipo	Valor
`address`	string, obrigatório	Seu endereço de carteira EVM.
`chain_id`	integer, obrigatório	Um ID de rede EVM disponível, obtido na API.

Resposta 200: challenge_id (string) e message (string).

Assine a mensagem retornada exatamente como recebida, usando a assinatura de mensagem pessoal EIP-191. Nunca envie a chave privada. Um desafio expirado ou já usado exige uma nova requisição.

POST /auth/wallet/verify

Troque um desafio assinado por uma sessão. Nenhum token bearer é necessário.

Campo	Tipo	Valor
`challenge_id`	string, obrigatório	ID retornado pela requisição de desafio.
`signature`	string, obrigatório	Assinatura hex da mensagem original exata.

{"challenge_id":"<challenge-id>","signature":"<0x-signature>"}

Resposta 200 (valores de exemplo):

{
  "token": "<session-token>",
  "expires_at": "2026-09-21T10:00:00Z",
  "user": {
    "user_id": "<user-id>",
    "onboarding_required": true,
    "mfa_required": false
  }
}

Envie token em Authorization: Bearer <session-token>. Use expires_at para acompanhar a expiração. Nenhum cookie é definido, então chamadas bearer não precisam de cabeçalho CSRF.

Provas inválidas ou já consumidas podem retornar 401 unauthorized. Se a requisição expirar depois que uma prova de uso único possa ter sido consumida, inicie um novo desafio em vez de reenviar a assinatura repetidamente.

MFA, quando ativado

A entrada por carteira não contorna o segundo fator da conta. Se user.mfa_required for verdadeiro, use o fator configurado com essa sessão antes das chamadas de negócio.

Para uma conta com TOTP, envie:

POST /api/v1/auth/totp/verify
Authorization: Bearer <session-token>
Content-Type: application/json

{"code":"<current-code>"}

Alterações sensíveis protegidas por MFA também podem retornar 403 mfa_required quando uma confirmação recente é necessária. Códigos de recuperação exigem a sessão primária; eles não são um método de login autônomo. Outros fatores de conta são descritos em Entrada na conta.

POST /onboarding

Quando user.onboarding_required for verdadeiro, crie o primeiro lojista. Uma conta que entrou apenas com uma carteira deve enviar o e-mail do proprietário humano junto com name, então peça esse e-mail ao seu humano primeiro:

{"name":"My merchant","email":"[email protected]"}

Envie com a sessão bearer e uma Idempotency-Key. O e-mail se torna um método de entrada dessa mesma conta. O Invoise envia um aviso à pessoa: ela abre o painel, entra com esse e-mail usando um código de uso único e chega à conta que o agente criou.

Erro	Significado
`400 email_required`	`email` está ausente. Peça ao seu humano.
`400 invalid_email`	O endereço é malformado.
`400 disposable_email`	Endereços de e-mail descartáveis não são aceitos. Use um endereço permanente.
`400 identity_already_linked`	O e-mail já pertence a outra conta. Peça um diferente.

Veja Fluxo do agente para os próximos passos.

POST /auth/logout

Encerra a sessão atual. Envie seu token bearer. Uma requisição bem-sucedida retorna 200; chamadas futuras com a sessão revogada são rejeitadas.

Para trabalho de pagamento contínuo, use uma chave de API da loja. Para a configuração após o login, siga Fluxo do agente.