API-Schlüssel

Wähle persönliche oder dienstbezogene Berechtigungen, speichere den geheimen Schlüsselwert einmalig und ersetze Zugangsdaten, ohne den Überblick über die zugehörigen Aufrufer zu verlieren.

Mit einem API-Schlüssel kann ein Aufrufer im Rahmen festgelegter Berechtigungen handeln. Ein persönlicher Schlüssel ist an die Mitgliedschaft und Berechtigungen einer Person gebunden. Ein Dienstschlüssel der Organisation gehört dagegen der Organisation. So bleibt die Automatisierung unabhängig davon, ob einzelne Teammitglieder ausscheiden. Mit RBAC kann ein Dienstschlüssel auch eine eigene Rolle und einen eigenen Zugriffsumfang für Ressourcen erhalten.

Der geheime Schlüsselwert wird bei der Erstellung angezeigt und lässt sich später nicht aus den Schlüsseleinträgen wiederherstellen. Speichere ihn sofort in einer Geheimnisverwaltung oder im Zugangsdaten-Speicher, den der Aufrufer unterstützt. Er darf nicht in Quelldateien, per Commit gespeicherten Konfigurationen, Screenshots oder Support-Nachrichten auftauchen.

Verwende einen persönlichen Schlüssel für Aufgaben in deinem Namen #

Erstelle und benenne in der ausgewählten Organisation unter Einstellungen → API-Schlüssel → Persönlich einen persönlichen Schlüssel. Jedes Mitglied kann einen solchen Schlüssel für den eigenen Gebrauch erstellen. Seine Berechtigungen richten sich nach der aktuellen Mitgliedschaft und den tatsächlich wirksamen Berechtigungen der Person, die ihn erstellt hat. Anders als ein Dienstschlüssel kann er weder eine separate Rolle noch einen auf einzelne Lokalisierungs-Engines begrenzten Zugriff erhalten.

Das eignet sich für einen lokalen Aufrufer, der im Namen der Person handelt, die ihn bedient. Scheidet das Mitglied aus oder verliert es Berechtigungen, ändert sich auch der Zugriff des Schlüssels. Verwende einen Dienstschlüssel, wenn die Automatisierung der Organisation nicht vom fortbestehenden Zugriff dieser Person abhängen soll.

Erstelle einen Dienstschlüssel #

Wähle in der ausgewählten Organisation unter Einstellungen → API-Schlüssel → Organisation die Option Neuer Organisationsschlüssel. Dienstschlüssel sind in jedem Tarif verfügbar. Für die Erstellung ist org:manage_api_keys erforderlich.

Ohne RBAC lässt sich der Zugriff eines Dienstschlüssels nicht einschränken: Er hat Lese- und Übersetzungszugriff auf alle Lokalisierungs-Engines der Organisation. Statt der Felder für Rolle und Engine zeigt das Erstellungsformular einen Hinweis.

Dieser grundlegende Zugriff erlaubt dem Schlüssel weder das Bearbeiten oder Löschen von Lokalisierungs-Engines noch die Prüfung von Übersetzungen oder die Verwaltung der Organisation.

Mit RBAC kannst du dem Schlüssel eine Rolle, einen auf bestimmte Lokalisierungs-Engines begrenzten Zugriff oder beides zuweisen und diese Einstellungen später ändern. Der Aufrufer muss berechtigt sein, die ausgewählte Rolle zu delegieren und mit jeder Lokalisierungs-Engine im festgelegten Zugriffsumfang zu übersetzen. Eine Leseberechtigung allein reicht nicht aus, um Übersetzungszugriff zu gewähren.

Als Dienstrollen sind engine:read und engine:translate zulässig. Eine Rolle muss zur Organisation gehören und darf keine weitergehenden administrativen Berechtigungen enthalten. Ein Dienstschlüssel kann auch ohne Rolle verwendet werden und sich auf gezielt erteilte Ressourcenberechtigungen stützen.

Konfiguriere den Zugriffsumfang für Lokalisierungs-Engines und Inhaltsressourcen getrennt und lies anschließend jedes gespeicherte Feld erneut aus. Eine Berechtigungsänderung kann fehlschlagen, während eine andere erfolgreich ist. Rollenberechtigungen und ausdrücklich erteilte Ressourcenberechtigungen summieren sich; ein enger Zugriffsumfang hebt weitergehende Zugriffsrechte aus einer Rolle nicht auf. Mit RBAC erhält ein Schlüssel, der weder eine passende Rolle noch Ressourcenberechtigungen hat, durch die Erstellung allein keine praktisch nutzbaren Übersetzungsberechtigungen.

Verwende die Oberfläche zur Schlüsselverwaltung, um Schlüssel zu erstellen und ihren Zugriffsumfang zu ändern. Wenn du diesen Lebenszyklus automatisierst, stelle sicher, dass der gewählte Client den benötigten Verwaltungsvorgang unterstützt. Gehe nicht davon aus, dass dies bei allen Clients der Fall ist.

Vor dem Entfernen von RBAC

Wird RBAC entfernt, erhalten gewöhnliche Dienstschlüssel wieder organisationsweiten Lese- und Übersetzungszugriff. Gespeicherte Rollen- und Engine-Einschränkungen begrenzen diesen Zugriff dann nicht mehr. Widerrufe oder rotiere die Schlüssel vor dem Entfernen von RBAC, wenn diese Einschränkungen erforderlich sind. Für zweckgebundene Zugangsdaten wie SCIM-Schlüssel gelten eigene Zugriffsanforderungen.

Rotiere oder widerrufe Zugangsdaten #

Bei der Rotation ersetzt du den Schlüssel manuell:

  1. Erstelle einen Ersatzschlüssel des vorgesehenen Typs mit den minimal erforderlichen Berechtigungen.
  2. Speichere den geheimen Schlüsselwert in der Geheimnisverwaltung des Aufrufers.
  3. Aktualisiere die abhängigen Aufrufer und teste über die jeweils unterstützte Schnittstelle einen kleinen, vorgesehenen Vorgang.
  4. Widerrufe den alten Schlüssel nach erfolgreichem Test. Wenn der Schlüssel offengelegt wurde und sofortige Maßnahmen nötig sind, widerrufe ihn zuerst und plane die dadurch entstehende Unterbrechung ein.
  5. Sieh dir die aktuellen Schlüsseleinträge und Fehler bei Aufrufern an, um übersehene Abhängigkeiten zu finden.

Ein Organisationsmitglied mit Zugriff auf den Schlüsseleintrag kann einen gewöhnlichen persönlichen Schlüssel oder Dienstschlüssel widerrufen. Diese Widerrufsberechtigung ist weiter gefasst als die Berechtigung, einen Dienstschlüssel zu erstellen oder dessen Zugriffsumfang zu ändern. SCIM-Schlüssel kann nur der Inhaber der Organisation widerrufen. Verwende bei der Abstimmung über die Entfernung die Kennung des Schlüssels, nicht seinen geheimen Wert.

Ein Widerruf löscht keine andernorts gespeicherten Kopien und beendet keine Browsersitzungen. Dieser Lebenszyklus sieht weder eine automatische Rotation noch einen automatischen Ablauf nach Zeitplan vor.

Konfiguriere den tatsächlich verwendeten Aufrufer #

REST-Anfragen verwenden den Header X-API-Key der ausgewählten API. Ein 401 deutet auf ein Authentifizierungsproblem hin, ein 403 auf fehlende Berechtigungen. Kontrolliere im ersten Fall die Zugangsdaten und im zweiten Fall die Berechtigungen und den Ressourcenzugriff der handelnden Identität. Verwende keine improvisierten URLs mit Zugangsdaten.

Informationen zur Übertragung und Speicherung durch den Aufrufer findest du unter API-Authentifizierung, CLI-Authentifizierung oder in der MCP-Verbindungsspezifikation. Die ausgewählte Lokalisierungs-Engine muss innerhalb des Berechtigungsumfangs dieses Aufrufers liegen.