Authentifizierung
Bearer-Token
Senden Sie bei jeder Anfrage Authorization: Bearer sk_live_…. Legen Sie einen Schlüssel nie in eine URL oder ein Cookie; es gibt keinen anderen Header dafür. Ein fehlender, fehlerhafter, widerrufener oder abgelaufener Schlüssel wird mit 401 unauthorized beantwortet, ohne Hinweis, welcher Fall vorliegt.
Ein Schlüssel gehört zu einem Arbeitsbereich. GET /v1/workspaces/current gibt ihn und seinen Tarif zurück. Wenn Sie X-Workspace-Id senden, muss der Header den Arbeitsbereich des Schlüssels nennen.
Schlüssel erstellen
Erstellen Sie Schlüssel in der App unter Settings → API. Editors, Admins und der Owner erstellen Schlüssel, die als sie selbst handeln; Admins können außerdem die Schlüssel aller umbenennen und widerrufen. Viewer können keine Schlüssel erstellen. Ein Arbeitsbereich kann 50 aktive Schlüssel halten.
Das Secret wird einmal angezeigt, und wir speichern nur seinen Hash. Die API erlaubt keine browserübergreifenden Aufrufe (Cross-Origin): Halten Sie Schlüssel auf Ihrem Server.
Scopes
Wählen Sie die Scopes beim Erstellen des Schlüssels; sie lassen sich danach nicht ändern (rotieren Sie den Schlüssel oder erstellen Sie einen neuen). Eine Anfrage braucht den Scope der Route, der in der API-Referenz neben jeder Route steht. Ein Schlüssel ohne ihn erhält 403 forbidden mit details.reason missing_scope.
codes:readCodes, ihre Versionen und Aktivität auflisten und lesen; Dateien herunterladen; Exporte und Massenläufe starten und lesen.Viewer oder höhercodes:writeCodes erstellen, ändern, pausieren, verschieben und löschen; Massenerstellung; Logos und Dateien hochladen.Editor oder höheranalytics:readStatistiken des Arbeitsbereichs und pro Code sowie Datensätze pro Scan.Viewer oder höhersubmissions:readAntworten auf gehostete Formulare. Sie enthalten personenbezogene Daten der Antwortenden.Editor oder höherfolders:readOrdner auflisten und lesen.Viewer oder höherfolders:writeOrdner erstellen, umbenennen, verschieben und löschen. Das Teilen bleibt in der App.Editor oder höhertemplates:readDesign-Vorlagen auflisten und lesen.Viewer oder höhertemplates:writeDesign-Vorlagen erstellen, ändern und löschen.Editor oder höherdomains:readEigene Domains und ihren Status auflisten, um eine für neue Codes zu wählen.Viewer oder höherwebhooks:readWebhook-Endpunkte und ihre Zustellungen auflisten.Admin oder höherwebhooks:writeWebhook-Endpunkte registrieren, ändern und löschen; ein Testereignis senden; erneut zustellen. Nur Admins.Admin oder höhertags:readListet die Tags des Arbeitsbereichs und wie viele Codes jeden tragen.Viewer oder höhertags:writeErstellt, benennt um, färbt um und löscht Tags. Codes zu taggen braucht Codes · write.Editor oder höhercards:readTeam-Visitenkarten und ihre Statistiken auflisten und lesen.Viewer oder höhercards:writeVisitenkarten erstellen, ändern, deaktivieren und neu zuweisen. Nur Admins.Admin oder höherconversions:writeConversions von Ihrem Server senden (Bestellungen, Anmeldungen) für den Scan-Trichter.Editor oder höherRollen
Ein Schlüssel darf nie mehr, als die aktuelle Rolle seines Erstellers erlaubt, begrenzt auf Editor. Wird der Ersteller zum Viewer herabgestuft, verliert der Schlüssel sofort seine Schreib-Scopes; verlässt der Ersteller den Arbeitsbereich, werden seine Schlüssel widerrufen.
webhooks:read und webhooks:write sind die Ausnahme: Nur Admins und der Owner können sie vergeben, und sie funktionieren nur so lange weiter, wie der Ersteller noch Admin ist.
Ordner- und IP-Beschränkungen
Ein Schlüssel kann auf bis zu 20 Ordner und ihre Unterordner beschränkt werden – etwa ein Schlüssel pro Kundenordner. Er sieht dann nichts außerhalb davon, und ein Schreibzugriff anderswo wird mit 403 und details.reason api_key_folder_restricted beantwortet.
Ein Schlüssel kann auch auf bis zu 20 IP-Bereiche in CIDR-Form (203.0.113.0/24) beschränkt werden. Ein Aufruf von anderswo wird mit 403 und details.reason ip_not_allowed beantwortet.
Ablauf und Rotation
Ein Schlüssel kann an einem von Ihnen gewählten Datum ablaufen. Beim Rotieren eines Schlüssels entsteht ein neues Secret mit demselben Namen, denselben Scopes und Beschränkungen; das alte Secret funktioniert standardmäßig noch 24 Stunden weiter (0 bis 168), sodass Sie das neue ohne Ausfallzeit ausrollen können. Das Widerrufen wirkt sofort.
Was ein Schlüssel nicht kann
Schlüssel rufen nur die Routen der API-Referenz auf. Ihr Konto, Mitglieder und Einladungen, Abrechnung, Arbeitsbereich-Einstellungen, Freigaben, Domain-Einrichtung und die API-Schlüssel selbst bleiben in der App: Diese Routen beantworten einen Schlüssel mit 403 forbidden und details.reason session_required.