API-Keys & Scopes

Die API authentifiziert jeden Request mit einem persönlichen API-Key. Ein Key gehört einem ratum-Benutzer. Dokumente, Kontingent, Audit-Trail und E-Mail-Absender sind die dieses Benutzers, genau wie im GUI.

GET /api/v1/api-keys/current HTTP/1.1
Host: api.ratum.ch
Authorization: Bearer ratum_live_…

Key erzeugen

1. In ratum anmelden und Profil → API-Zugang öffnen.
2. Namen vergeben (z. B. «ERP Produktion»), Modus (Live oder Test), Scopes und optional ein Ablaufdatum wählen.
3. Erzeugen und den Key sofort kopieren. ratum zeigt ihn genau einmal an und speichert nur einen Hash. Ein verlorener Key lässt sich nicht wiederherstellen, nur widerrufen und neu erzeugen.

Bezahlter Tarif nötig

API-Keys gibt es nur in bezahlten Tarifen. Fällt das Konto in den Gratis-Tarif zurück, werden die Keys suspendiert (nicht gelöscht): Requests bekommen 403 plan_required, bis wieder eine Zahlungsmethode hinterlegt ist.

Key-Präfixe

Präfix	Modus	Wirkung
ratum_live_	Live	echte Signaturen, E-Mails, Kontingentverbrauch
ratum_test_	Test	ohne Kosten und Mails, Wasserzeichen «TEST», siehe Test-Modus

Ein Key besteht aus dem Präfix und 40 zufälligen Zeichen [A-Za-z0-9]. Im GUI erkennst du ihn am sichtbaren Anfang (ratum_live_ + 6 Zeichen). Durch das eindeutige Präfix finden Secret-Scanner einen geleakten Key zuverlässig. Behandle Keys wie Passwörter: nur serverseitig, in einem Secret-Store, nie im Browser, in Apps oder in Git.

Scopes

Jeder Key hat einen oder mehrere Scopes. Fehlt der nötige Scope, antwortet die API mit 403 insufficient_scope.

Scope	Erlaubt
documents:read	Dokumente, Signer, Felder, Audit-Trail und Downloads lesen
documents:write	Dokumente anlegen und löschen, Signer und Felder bearbeiten
documents:send	Dokumente versenden (/send; createAndSend braucht zusätzlich documents:write), Signer erinnern (/resend)
signers:link	Signier-Links abrufen bei delivery: none
webhooks:manage	Webhook-Endpoints verwalten; nur für Live-Keys, Test-Keys können ihn nicht erhalten (422)

GET /api-keys/current funktioniert mit jedem gültigen Key und braucht keinen Scope.

Least Privilege

Gib einem Key nur die Scopes, die das System braucht. Ein Reporting-Job kommt mit documents:read aus.

Ablauf, Widerruf und Kontosperre

• Ablaufdatum (optional): danach antwortet die API mit 401 unauthenticated.
• Widerruf: im GUI jederzeit möglich, wirkt sofort.
• Gesperrtes Konto: wird der Benutzer in ratum gesperrt, gelten auch seine Keys nicht mehr.
• Ein Key hängt an seinem Benutzer. Verlässt die Person die Firma, sollte die Integration auf einen Key eines anderen Benutzers umziehen.

Was die API-Subdomain nicht kann

API-Keys gelten nur auf api.ratum.ch; auf anderen ratum-Hosts antwortet die API mit 401. Umgekehrt nimmt api.ratum.ch ausschliesslich API-Key-Requests an. Cookies werden ignoriert, CORS-Header gibt es keine. Die API ist also nicht für Aufrufe aus dem Browser gedacht. Routen ausserhalb der API-Referenz antworten mit 404.