Agent sign-in

Already have a shop API key? Skip sign-in and use the payment API. An agent only needs wallet sign-in when it must set up or administer an account.

Wallet sign-in is for agents only. Send these requests from a server or script: a request with an Origin header, which every browser adds, is refused with 403 wallet_sign_in_agents_only. The dashboard does not offer wallet sign-in or wallet linking.

1. Request a message

Use an EVM wallet you control. Its private key stays with your signing tool and is never sent to Invoise.

curl -X POST 'https://platform.invoise.me/api/v1/auth/wallet/challenge' \
  -H 'Content-Type: application/json' \
  -d "{\"address\":\"${WALLET_ADDRESS:?}\",\"chain_id\":${CHAIN_ID:?}}"

Set WALLET_ADDRESS to your EVM address and CHAIN_ID to an available EVM network ID from the API. The response contains challenge_id and message.

2. Sign the returned message

Use your wallet’s EIP-191 personal-message signing method. Sign message exactly as received, including whitespace. This is a message signature, not a transaction.

The challenge is short-lived and single-use. If it expires or is consumed, request a new one.

3. Exchange the signature for a session

curl -X POST 'https://platform.invoise.me/api/v1/auth/wallet/verify' \
  -H 'Content-Type: application/json' \
  -d '{"challenge_id":"<challenge-id>","signature":"<0x-signature>"}'

Save token securely and check expires_at, user.mfa_required and user.onboarding_required in the response.

Invoise sets no cookie. Send the session in Authorization: Bearer <token>; it needs no CSRF header.

4. Complete setup

Condition	Next step
user.mfa_required: true	Complete the configured second factor before business requests. Wallet sign-in does not bypass MFA.
user.onboarding_required: true	Ask your human for their email, then create the first merchant through /onboarding with name and email. Without the email the answer is 400 email_required; a disposable address returns 400 disposable_email.
Sign-in complete	Continue with Agent workflow to choose a merchant, create a shop and issue a shop API key.

Use the session for setup and the scoped API key for payment work. If a session expires, authenticate again. See Auth reference for request and response fields.