Agent auth reference

All paths below use https://platform.invoise.me/api/v1. Send JSON with Content-Type: application/json. Sign-in requests do not need an idempotency key.

Wallet sign-in is for agents only. A request with an Origin header, as every browser request has, returns 403 wallet_sign_in_agents_only. Call these endpoints from a server or script.

POST /auth/wallet/challenge

Request a message to sign. No credentials required.

Field	Type	Value
address	string, required	Your EVM wallet address.
chain_id	integer, required	An available EVM network ID from the API.

200 response: challenge_id (string) and message (string).

Sign the returned message exactly as received using EIP-191 personal-message signing. Never send the private key. An expired or used challenge requires a new request.

POST /auth/wallet/verify

Exchange a signed challenge for a session. No bearer token required.

Field	Type	Value
challenge_id	string, required	ID returned by the challenge request.
signature	string, required	Hex signature of the exact original message.

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

200 response (example values):

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

Send token in Authorization: Bearer <session-token>. Use expires_at to track expiry. No cookie is set, so bearer calls need no CSRF header.

Invalid or consumed proofs can return 401 unauthorized. If the request times out after a one-time proof may have been consumed, start a fresh challenge instead of repeatedly sending the signature.

MFA, when enabled

Wallet sign-in does not bypass the account’s second factor. If user.mfa_required is true, use the configured factor with this session before business calls.

For an account with TOTP, send:

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

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

MFA-protected sensitive changes can also return 403 mfa_required when a fresh confirmation is needed. Recovery codes require the primary session; they are not a standalone login method. Other account factors are described in Account sign-in.

POST /onboarding

When user.onboarding_required is true, create the first merchant. An account that signed in only with a wallet must send the human owner’s email next to name, so ask your human for it first:

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

Send it with the bearer session and an Idempotency-Key. The email becomes a sign-in method of this same account. Invoise sends the person a notice: they open the dashboard, sign in with that email using a one-time code and land in the account the agent created.

Error	Meaning
400 email_required	email is missing. Ask your human for it.
400 invalid_email	The address is malformed.
400 disposable_email	Disposable email addresses are not accepted. Use a permanent address.
400 identity_already_linked	The email already belongs to another account. Ask for a different one.

See Agent workflow for the next steps.

POST /auth/logout

End the current session. Send its bearer token. A successful request returns 200; future calls with the revoked session are rejected.

For ongoing payment work, use a shop API key. For setup after login, follow Agent workflow.