API-Schlüssel und Scopes

Jede Anfrage an die API und den MCP-Server braucht einen API-Schlüssel. Ein Schlüssel gehört zu einem Arbeitsbereich, handelt als der Inhaber oder Admin, der ihn erstellt hat, und erreicht nur die Endpunkte, die seine Scopes erlauben. Schlüssel beginnen mit gr_live_, gefolgt von 43 Buchstaben, Ziffern, Bindestrichen und Unterstrichen.

Einen Schlüssel erstellen

1. 1

   API und Agenten öffnen

   Geh in Gradiently zu Einstellungen › API und Agenten und wähl den Arbeitsbereich, für den der Schlüssel ist. Nur Inhaber und Admins dieses Arbeitsbereichs können Schlüssel erstellen.

2. 2

   Ihn benennen

   Gib ihm unter Schlüssel erstellen im Feld Name einen Namen danach, wo du ihn einsetzt, etwa Claude Code oder Nächtlicher Export, damit du später weißt, welchen du widerrufen musst.

3. 3

   Festlegen, was er kann

   Wähl unter Was er kann die Berechtigungen aus, die er braucht, mindestens eine. Der nächste Abschnitt erklärt jede davon.

4. 4

   Ihn einmal kopieren

   Wähl Schlüssel erstellen. Der Schlüssel erscheint unter Kopiere deinen Schlüssel jetzt, und das ist das einzige Mal, dass er angezeigt wird. Kopier ihn in einen Passwort-Manager oder deinen Secret-Speicher und wähl dann Ich hab ihn gespeichert.

Wer einen Schlüssel erstellt, bekommt eine E-Mail, wenn er erstellt und wenn er widerrufen wird, mit seinem Namen, dem Anfang des Schlüssels und seinen Berechtigungen. Die Liste in den Einstellungen zeigt für jeden aktiven Schlüssel den Namen, den Anfang des Schlüssels, wann er zuletzt verwendet wurde und wie viele Berechtigungen er hat.

Scopes

Ein Scope ist eine Berechtigung. Eine Anfrage braucht jeden Scope, den ihr Endpunkt nennt, und jedes MCP-Werkzeug braucht die Scopes aller Anfragen, die es stellt. Vergib nur, was die Aufgabe braucht.

Bei neuen Schlüsseln sind „Designs lesen“, „Designs erstellen und bearbeiten“, „Marks suchen“ und „Marken generieren“ vorausgewählt. Marks sichern bleibt aus, bis du es wählst, denn beim Sichern wirst du, der Ersteller des Schlüssels, zum Halter eines Marks.

Einen Schlüssel rotieren

Schlüssel laufen nicht ab, und Name und Scopes eines Schlüssels lassen sich nach dem Erstellen nicht ändern. Um einen Schlüssel zu rotieren oder zu ändern, was er kann, ersetze ihn:

1. 1

   Den neuen Schlüssel erstellen

   Erstelle einen Schlüssel mit den gewünschten Scopes und einem Namen, an dem du ihn vom alten unterscheiden kannst.

2. 2

   Deine Tools umstellen

   Setz den neuen Schlüssel überall ein, wo der alte verwendet wurde: in deinem MCP-Client, deinem Secret-Speicher oder deinen Deployment-Einstellungen.

3. 3

   Den alten Schlüssel widerrufen

   Sobald sich das Datum hinter verwendet am beim alten Schlüssel in der Liste nicht mehr ändert, widerrufe ihn.

Einen Schlüssel widerrufen

Wähl unter Einstellungen › API und Agenten neben dem Schlüssel Widerrufen und bestätige mit Schlüssel widerrufen. Alles, was ihn verwendet, hört sofort auf zu funktionieren, und das lässt sich nicht rückgängig machen. Inhaber und Admins des Arbeitsbereichs können jeden seiner Schlüssel widerrufen.

Ein Schlüssel hört auch von selbst auf zu funktionieren, wenn sein Ersteller den Arbeitsbereich verlässt, unter Admin herabgestuft wird oder sein Konto deaktiviert wird. Schlüssel, die eine Person erstellt hat, werden widerrufen, wenn sie aus dem Arbeitsbereich entfernt oder herabgestuft wird.

Was ein Schlüssel nie kann

Manches braucht immer eine bei Gradiently angemeldete Person, egal welche Scopes der Schlüssel hat:

• Schlüssel erstellen, auflisten oder widerrufen.
• Das Konto ändern: Profil, E-Mail, Passwort, Anmeldesitzungen oder das Konto löschen.
• Auf die Abrechnung zugreifen: Tarife, Checkout, Zahlungen, Aufladungen von KI-Credits, Guthaben und Auszahlungen. Ein Sichern oder Kauf, der eine Zahlung braucht, hält an und verlangt den Checkout in Gradiently.
• Einen Mark weitergeben: ihn an jemand anderen übertragen, freigeben, zum Verkauf anbieten, verlängern oder veröffentlichen.
• Das Halten oder die Lizenz eines Marks auf den Arbeitsbereich übertragen. Marks, die ein Schlüssel sichert, hält sein Ersteller, und jede Lizenz bleibt bei ihm.
• Ändern, wer im Arbeitsbereich ist oder welche Rollen die Mitglieder haben, oder den Arbeitsbereich umbenennen, übertragen oder löschen. Mit members:write kann er nur Einladungen verschicken.
• Auf einen anderen Arbeitsbereich als seinen eigenen zugreifen, auch nicht auf einen, zu dem sein Ersteller gehört.
• Die Administration von Gradiently nutzen.

Schlüssel sicher aufbewahren

Gradiently speichert von jedem Schlüssel nur einen Hash und seinen Anfang für die Anzeige, ein verlorener Schlüssel lässt sich also nicht noch einmal anzeigen: Widerrufe ihn und erstelle einen neuen. Wenn du glaubst, dass ein Schlüssel missbraucht wurde, widerrufe ihn und sag uns Bescheid.