Einstieg
Authentifizierung
Ein API-Schlüssel im Authorization-Header. Was er darf, ist die Schnittmenge aus seinen Scopes und den Rechten der Organisation.
Der Schlüssel
Schlüssel erzeugen und widerrufen Sie angemeldet unter Entwickler — dort legen Sie auch die Scopes fest, und der Klartext wird genau einmal angezeigt.
curl https://signido.de/api/v1/signature-requests \
-H "Authorization: Bearer $SIGNIDO_API_KEY"- sg_live_<id>_<secret>
- Produktion. Erzeugt echte Signaturen, echte Anbieter-Aufrufe und echte Rechnungspositionen.
- sg_test_<id>_<secret>
- Sandbox. Keine Rechnungen, keine echten Vertrauensdienste, und alles, was damit entsteht, trägt
isTestMode: true. Eine Test-Signatur ist keine rechtlich verwertbare Signatur und wird auch nicht als solche ausgegeben. - Der Klartext wird einmal gezeigt
- Gespeichert wird nur ein argon2id-Hash. Ein verlorener Schlüssel kann nicht ausgelesen, sondern nur widerrufen und ersetzt werden.
- Optionale IP-Beschränkung
- Ein Schlüssel kann auf CIDR-Bereiche begrenzt werden. Eine leere Liste bedeutet keine Beschränkung; eine gefüllte Liste, die nicht passt, führt zu 401.
Scopes
Ein Scope beschreibt eine Fähigkeit, keine Ressource. Was ein Schlüssel wirklich darf, ist die Schnittmenge aus seinen Scopes und den Berechtigungen der Organisation, in der er lebt. Ein Schlüssel mit documents:write in einer Organisation ohne aktives Abonnement darf nichts erstellen — und das ist kein Fehler in der Scope-Liste, sondern der Zweck der Schnittmenge.
| Scope | Berechtigt zu |
|---|---|
| documents:read | Dokumente lesen und herunterladen |
| documents:write | Dokumente erstellen, ändern, löschen |
| requests:read | Signaturanfragen, Empfänger und Felder lesen |
| requests:write | Signaturanfragen erstellen, ändern, abbrechen |
| requests:send | Versenden, erinnern, übergeben, reaktivieren |
| templates:read | Vorlagen lesen und verwenden |
| templates:write | Vorlagen erstellen, ändern, löschen, freigeben |
| contacts:read | Kontakte lesen |
| contacts:write | Kontakte erstellen, ändern, löschen |
| webhooks:read | Webhook-Endpunkte und Zustellprotokolle lesen |
| webhooks:write | Webhook-Endpunkte verwalten |
| webforms:read | Web-Formulare lesen |
| webforms:write | Web-Formulare verwalten |
| bulk:read | Massenversände lesen |
| bulk:write | Massenversände starten |
| team:read | Team und Rollen lesen |
| billing:read | Abonnement und Rechnungen lesen |
| usage:read | Nutzungsdaten lesen |
| audit:read | Nachweisverläufe lesen und exportieren |
Fehlt der Scope, antwortet die API mit 403 SCOPE_INSUFFICIENT. Fehlt die Berechtigung der Organisation, mit 403 FORBIDDEN. Die beiden Codes zu unterscheiden lohnt sich: das erste behebt man im Schlüssel, das zweite in der Rolle.
Was ein Schlüssel nicht kann
- Sich anmelden. Registrierung, Anmeldung, MFA und Passkeys sind eine Browser-Sitzung und stehen nicht unter
/v1zur Verfügung. - Das Team verwalten. Rollen ändern, Mitglieder einladen, Inhaberschaft übertragen, ein Konto löschen: das sind menschliche Handlungen, und sie verlangen zusätzlich eine kürzlich per zweitem Faktor bestätigte Sitzung.
- Eine andere Organisation adressieren. Die Organisation ergibt sich aus dem Schlüssel. Es gibt keinen Parameter dafür.
- Sich selbst erweitern. Ein Schlüssel kann keine Schlüssel erstellen.