Skip to main content
API-Schlüssel authentifizieren Anfragen an die /v1 Public API. Jeder Schlüssel gehört zu einem Servicekonto und wird auf der Detailseite dieses Kontos im Developer Hub erstellt. Verwenden Sie einen API-Schlüssel mit eingeschränktem Geltungsbereich für eine private Backend-Integration, wenn die sichere Speicherung und Rotation eines Secrets Ihre Anforderungen erfüllt. Ein OAuth-Client oder ein Token-Austausch ist nicht erforderlich. Lesen Sie Authentifizierung, falls Ihre Organisation stattdessen kurzlebige OAuth-Zugriffstokens verlangt.

​
Aufbau eines Schlüssels

  • Kennung — beginnt mit ak_. Kann unbedenklich in Tickets, Protokollen und Konfigurationen referenziert werden; allein gewährt sie keinerlei Zugriff.
  • Secret — beginnt mit lsk_live_. Dies sind die Zugangsdaten, die Ihre Integration vorlegt. Es wird einmalig bei der Erstellung oder Rotation angezeigt und kann später nicht mehr abgerufen werden. Die Schlüsselliste zeigt nur die letzten vier Zeichen an (zum Beispiel lsk_live_…xQc4), damit Sie eine Zeile den Zugangsdaten zuordnen können, die ein Aufrufer besitzt.
  • Berechtigungen — eine Teilmenge der Berechtigungen des zugehörigen Servicekontos, die bei der Erstellung ausgewählt wird. Ein Schlüssel kann nie mehr, als sein Konto erlaubt.
  • Ablaufdatum — obligatorisch. Jeder Schlüssel hat ein Ablaufdatum.
Speichern Sie Secrets in einem Secret-Manager, sobald sie angezeigt werden. Übertragen Sie sie niemals in die Versionsverwaltung, binden Sie sie nicht in clientseitigen Code ein und teilen Sie sie nicht im Chat. Jeder, der das Secret besitzt, kann mit den Berechtigungen des Schlüssels handeln.

​
Schlüssel erstellen

Auf der Detailseite des Servicekontos erstellen Sie einen Schlüssel in vier Schritten: Benennen Sie ihn, wählen Sie die Berechtigungen aus, die dieser konkrete Schlüssel benötigt, legen Sie ein Ablaufdatum fest — 30, 90 oder 365 Tage oder einen benutzerdefinierten Zeitraum von bis zu einem Jahr — und prüfen Sie Ihre Angaben. Das Secret wird nach Abschluss einmalig angezeigt. Beschränken Sie jeden Schlüssel auf die kleinstmögliche Berechtigungsmenge, die sein Aufrufer benötigt, auch wenn das Konto mehr erlaubt. Falls ein Schlüssel offengelegt wird, bestimmen seine Berechtigungen das Ausmaß des Schadens.

​
Rotation ohne Ausfallzeit

Bei der Rotation wird ein neues Secret ausgestellt und ein Überlappungszeitraum gestartet — 1 Stunde, 24 Stunden oder 7 Tage —, in dem das alte Secret weiterhin funktioniert. So können Sie das neue Secret in Ihrem eigenen Tempo in Ihren Deployments ausrollen:
1

Schlüssel rotieren

Wählen Sie einen Überlappungszeitraum, der Ihren langsamsten Deployment-Pfad abdeckt. Das neue Secret wird nur einmal angezeigt — speichern Sie es umgehend.
2

Integrationen aktualisieren

Ersetzen Sie das alte Secret überall dort, wo es konfiguriert ist. Der Status des Schlüssels wird als „in Überlappung“ angezeigt, bis der Zeitraum endet.
3

Vor Ablauf des Zeitraums überprüfen

Verwenden Sie die Anfrageprotokolle, um zu bestätigen, dass der Datenverkehr auf das neue Secret umgestellt wurde. Wenn die Überlappung endet, kann das alte Secret nicht mehr zur Authentifizierung verwendet werden.
Rotieren Sie auch vor dem Ablauf: Schlüssel, deren Ablaufdatum näher rückt, werden in der Schlüsselliste als bald ablaufend markiert. Ein abgelaufener Schlüssel authentifiziert nicht mehr — Anfragen mit diesem Schlüssel geben ein 401 mit dem Code credential_expired zurück.

​
Sofort widerrufen

Der Widerruf wird sofort wirksam und ist endgültig — es gibt keinen Überlappungszeitraum und keine Möglichkeit, ihn rückgängig zu machen. Widerrufen Sie einen Schlüssel, sobald Sie vermuten, dass sein Secret offengelegt wurde; rotieren Sie stattdessen, wenn Sie intakte Zugangsdaten ersetzen. Anfragen mit einem widerrufenen Schlüssel geben ein 401 mit dem Code credential_revoked zurück. Wenn Sie alle Schlüssel einer Integration auf einmal stoppen müssen, deaktivieren Sie stattdessen das zugehörige Servicekonto.