Agent-Auth-Referenz

Alle unten stehenden Pfade verwenden https://platform.invoise.me/api/v1. Senden Sie JSON mit Content-Type: application/json. Anmeldeanfragen benötigen keinen Idempotenzschlüssel.

Die Wallet-Anmeldung ist nur für Agenten. Eine Anfrage mit einem Origin-Header, wie ihn jede Browseranfrage hat, gibt 403 wallet_sign_in_agents_only zurück. Rufen Sie diese Endpunkte von einem Server oder Skript aus auf.

POST /auth/wallet/challenge

Fordert eine zu signierende Nachricht an. Keine Zugangsdaten erforderlich.

Feld	Typ	Wert
`address`	string, erforderlich	Ihre EVM-Wallet-Adresse.
`chain_id`	integer, erforderlich	Eine verfügbare EVM-Netzwerk-ID aus der API.

200-Antwort: challenge_id (string) und message (string).

Signieren Sie die zurückgegebene Nachricht genau wie erhalten mit EIP-191-Personal-Message-Signing. Senden Sie niemals den privaten Schlüssel. Eine abgelaufene oder verwendete Challenge erfordert eine neue Anfrage.

POST /auth/wallet/verify

Tauscht eine signierte Challenge gegen eine Sitzung. Kein Bearer-Token erforderlich.

Feld	Typ	Wert
`challenge_id`	string, erforderlich	Von der Challenge-Anfrage zurückgegebene ID.
`signature`	string, erforderlich	Hex-Signatur der exakten ursprünglichen Nachricht.

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

200-Antwort (Beispielwerte):

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

Senden Sie token in Authorization: Bearer <session-token>. Verwenden Sie expires_at, um den Ablauf zu verfolgen. Es wird kein Cookie gesetzt, sodass Bearer-Aufrufe keinen CSRF-Header benötigen.

Ungültige oder bereits verwendete Nachweise können 401 unauthorized zurückgeben. Wenn die Anfrage nach einem Timeout scheitert, nachdem ein einmaliger Nachweis möglicherweise bereits verwendet wurde, starten Sie eine neue Challenge, statt die Signatur wiederholt zu senden.

MFA, falls aktiviert

Die Wallet-Anmeldung umgeht nicht den zweiten Faktor des Kontos. Wenn user.mfa_required true ist, verwenden Sie den konfigurierten Faktor mit dieser Sitzung vor Geschäftsaufrufen.

Senden Sie für ein Konto mit TOTP:

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

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

MFA-geschützte sensible Änderungen können auch 403 mfa_required zurückgeben, wenn eine frische Bestätigung erforderlich ist. Wiederherstellungscodes erfordern die primäre Sitzung; sie sind keine eigenständige Anmeldemethode. Weitere Kontofaktoren werden in Konto-Anmeldung beschrieben.

POST /onboarding

Erstellen Sie den ersten Händler, wenn user.onboarding_required true ist. Ein Konto, das sich nur mit einer Wallet angemeldet hat, muss die E-Mail-Adresse des menschlichen Inhabers zusammen mit name senden, fragen Sie also zuerst Ihren Menschen danach:

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

Senden Sie es mit der Bearer-Sitzung und einem Idempotency-Key. Die E-Mail-Adresse wird zu einer Anmeldemethode desselben Kontos. Invoise sendet der Person einen Hinweis: Sie öffnet das Dashboard, meldet sich mit dieser E-Mail-Adresse per Einmalcode an und landet in dem Konto, das der Agent erstellt hat.

Fehler	Bedeutung
`400 email_required`	`email` fehlt. Fragen Sie Ihren Menschen danach.
`400 invalid_email`	Die Adresse ist fehlerhaft.
`400 disposable_email`	Wegwerf-E-Mail-Adressen werden nicht akzeptiert. Verwenden Sie eine dauerhafte Adresse.
`400 identity_already_linked`	Die E-Mail-Adresse gehört bereits zu einem anderen Konto. Fragen Sie nach einer anderen.

Siehe Agenten-Workflow für die nächsten Schritte.

POST /auth/logout

Beendet die aktuelle Sitzung. Senden Sie deren Bearer-Token. Eine erfolgreiche Anfrage gibt 200 zurück; zukünftige Aufrufe mit der widerrufenen Sitzung werden abgelehnt.

Verwenden Sie für laufende Zahlungsarbeit einen Shop-API-Schlüssel. Folgen Sie für die Einrichtung nach der Anmeldung dem Agenten-Workflow.