Wissen
API-Schlüssel und Berechtigungen (Scopes)
Wie Sie API-Schlüssel anlegen, schützen und erneuern und welche 36 Berechtigungen (Scopes) Sie vergeben können. Mit Vorlagen und Standardwerten.
5 Min. Lesezeit · Stand: 07.10.2026
Ein API-Schlüssel erlaubt es Ihrem System, OneSign ohne Anmeldung im Browser aufzurufen. Was der Schlüssel darf, legen seine Berechtigungen (Scopes) fest. Vergeben Sie nur, was ein Aufruf braucht.
Schlüssel anlegen und schützen
- Inhaber und Admins legen Schlüssel im Dashboard unter „Entwickler → API-Schlüssel“ an. Betrachter sehen keine Schlüssel; Versender, Unterzeichner und Buchhaltung sehen den Bereich „Entwickler“ nicht.
- Jeder Schlüssel gehört zu einem Modus: Test-Schlüssel (qgw_test_…) berühren nichts Echtes und kosten nichts, Live-Schlüssel (qgw_live_…) arbeiten mit echten Vorgängen.
- Der vollständige Schlüssel wird nur einmal angezeigt. Danach sehen Sie nur noch Präfix und die letzten vier Zeichen. Geht er verloren, erneuern Sie den Schlüssel.
- Optional begrenzen Sie einen Schlüssel auf IP-Adressen oder -Bereiche (bis zu 50 Einträge) und geben ihm ein Ablaufdatum.
- Einen Schlüssel können Sie jederzeit widerrufen. Webhook-Abos, die er angelegt hat, werden dabei deaktiviert.
Die 36 vergebbaren Berechtigungen
Diese 36 Scopes lassen sich heute vergeben. Weitere Scopes gibt es erst, wenn ihre Routen veröffentlicht sind. Die Spalte „Standard aus“ nennt die Scopes, die bei einem neuen Schlüssel nicht vorausgewählt sind: alles, was signiert, abrechnet, Signierlinks herausgibt, Zugangsdaten oder Personendaten liest, Workflows ändert oder ausführt, die Organisation ändert oder externe Dritte erreicht.
| Berechtigungen | Wofür | Standard aus |
|---|---|---|
| read, sign, verify | Signatur-Routen: lesen, Signaturen auslösen, Signaturen prüfen | sign, verify |
| certificates:read, certificates:purchase, certificates:credentials, certificates:manage | Zertifikate lesen, kaufen, Zugangsdaten lesen, Einwilligung anfordern | certificates:purchase, certificates:credentials, certificates:manage |
| envelopes:read, envelopes:write, envelopes:signing_urls, envelopes:sign | Vorgänge lesen und anlegen, Signierlinks herausgeben, qualifizierter Schritt eines Mitglieds | envelopes:signing_urls, envelopes:sign |
| documents:read | Dokumente und Nachweise lesen | – |
| templates:read, templates:write | Vorlagen lesen und ändern | – |
| forms:read, forms:write, submissions:read, submissions:write | Formulare und Einsendungen | – |
| contracts:read, contracts:write, contracts:external_reminders | Verträge, Fristen und Erinnerungen; externe Erinnerungen erreichen Dritte | contracts:external_reminders |
| workflows:read, workflows:write, workflows:run | Workflows lesen, ändern und ausführen | workflows:write, workflows:run |
| seals:read, seals:use | Siegel lesen und verwenden | seals:use |
| contacts:read, contacts:write | Kontakte | – |
| identity:read, identity:write | Identitätsprüfungen (Objekte tragen Namen und E-Mail) | identity:read, identity:write |
| webhooks:read, webhooks:manage | Ereignisse und Zustellungen lesen; Webhook-Abos ändern | webhooks:manage |
| org:read, org:manage, members:manage, billing:read | Organisation lesen und ändern (Einbettung), Mitglieder verwalten, Kostenschätzungen und Ausgaben lesen | org:manage, members:manage |
Vorlagen und Ergänzen
- Vorlagen im Dialog: „Standard“ (alle vorausgewählten Scopes), „Integration“ (Standard plus webhooks:manage und envelopes:signing_urls), „Nur lesen“ (alle Lese-Scopes) und „Einzelsignatur (QES)“ (sign, read, verify, certificates:read). Danach lässt sich jede Auswahl einzeln ändern.
- Der Scope envelopes:sign (ein Mitglied unterschreibt automatisch mit seiner Einwilligung) steckt in keiner Vorlage und lässt sich nur einzeln wählen.
- „Berechtigungen ergänzen“ fügt einem aktiven Schlüssel Scopes hinzu, entfernt aber nie welche. Das geht nur im Dashboard, nie mit einem Schlüssel. envelopes:sign wird nur in einem eigenen Schritt ergänzt.
- Ein Aufruf ohne den nötigen Scope antwortet mit 403 und dem Fehlercode 9002; die Fehlermeldung nennt den fehlenden Scope. Bei Webhook-Abos und Ereignissen stehen die fehlenden Scopes zusätzlich in details.missingScopes.