API-Keys sind die Bearer-Tokens, mit denen deine CI und der GitHub-Action-Wrapper sich gegen das Portal authentifizieren. Jeder Key gehört zu einem Benutzer, gilt unabhängig vom Login-Cookie und kann unabhängig widerrufen werden.
Auf derselben Seite stehen außerdem die Autorisierten Geräte, also die
Entwicklermaschinen, die du mit codecharter login angemeldet hast. Das ist
ein eigenes und deutlich eingeschränkteres Credential, es kann nur eine Lizenz
erneuern, und es ist unter
Autorisierte Geräte beschrieben.
Key erzeugen
Auf /api-keys:
- Name vergeben, frei wählbar (bis zu 120 Zeichen). Empfehlung: was der
Key tut bzw. wo er liegt, z.B.
acme-web-ci. Den Namen siehst du später in der Übersicht und beim Audit. - Laufzeit wählen: 30 Tage, 90 Tage, 1 Jahr oder unbegrenzt. 1 Jahr ist vorausgewählt. Kürzere Laufzeiten sind sicherer, brauchen aber häufigeren Austausch.
- Key erzeugen wählen.
Jeder Key trägt den Scope read:rules. Er deckt das Lesen deiner Regeln und
Profile sowie das Herunterladen von Bundles ab. Setze zusätzlich
write:rules, damit der Key mit codecharter push Entwürfe hochladen darf;
lass ihn für reine Lese-Keys in CI weg. Administratoren können einem Key
zusätzlich den Scope register:engines für Release-Automatisierung geben. Die
Scopes jedes Keys werden in der Key-Liste angezeigt.
Hinweis: Die meisten CLI-Befehle brauchen gar keinen API-Key mehr. analyze,
restore, update und verify authentifizieren sich über die installierte
codecharter.license, und push greift ebenfalls darauf zurück. Ein API-Key ist
nur nötig, wenn keine Lizenz auf den Runner gelangt (dann braucht push einen
Key mit write:rules).
Auf einer Entwicklermaschine brauchst du in der Regel überhaupt keinen Key:
codecharter login meldet diese Maschine über deinen Browser an und hält ihre
Lizenz aktuell. Behalte API-Keys für CI und Automatisierung, siehe
Credentials und Reihenfolge.
Den Klartext-Wert kopieren
Direkt nach der Erzeugung zeigt das Portal einmal den vollen Klartext des Keys, in einem Warnhinweis auf der Seite. Kopiere ihn sofort: wir speichern nur einen Hash, und der Klartext ist weg, sobald du die Seite verlässt oder neu lädst.
Keys beginnen mit cgk_, und die Key-Liste zeigt die ersten 12 Zeichen
jedes Keys. So kannst du ein gespeichertes Secret später dem passenden
Listeneintrag zuordnen.
Wenn du den Wert verloren hast: einfach einen neuen Key erzeugen und den alten widerrufen. Wir können dir den Wert nachträglich nicht zeigen.
Key in deiner CI hinterlegen
Speichere den kopierten Wert als Secret in deinem CI-System. Details pro CI-System unter API-Keys in Secrets.
GitHub Actions Schnellanleitung:
Repo → Settings → Secrets and variables → Actions → New repository secret
Name: CODECHARTER_API_KEY
Value: <der Klartext-Wert>
Im Workflow:
- uses: bochmann-software/codecharter@v1
with:
api-key: ${{ secrets.CODECHARTER_API_KEY }}
Key widerrufen
Im Portal in der API-Key-Liste neben dem Eintrag Widerrufen wählen und im Bestätigungsdialog bestätigen. Ab dem nächsten CI-Aufruf bekommt der Key 401 Unauthorized.
Ein Widerruf ist endgültig. Wenn du dich vertan hast, erzeuge einfach einen neuen Key.
Key austauschen
Wenn ein Key kompromittiert ist oder ein Team-Mitglied geht, das den Klartext gesehen haben könnte, ersetze ihn so:
- Neuen Key erzeugen im Portal.
- Im CI-System den neuen Wert in dieselbe Secret-Variable
(
CODECHARTER_API_KEY) schreiben. - Einen CI-Lauf auslösen, um zu bestätigen, dass der neue Key funktioniert.
- Alten Key widerrufen.
Mehrere Keys dürfen gleichzeitig aktiv sein. Der neue Key ist sofort nutzbar, während der alte noch gilt. Das ergibt ein sauberes Wechselfenster ohne Ausfallzeit, bevor du den alten Key widerrufst.
Was ein Key kann
Ein Key authentifiziert die Portal-Aufrufe der CLI: das Abrufen und Erneuern
der kurzlebigen Lizenz, das Herunterladen von CLI-Release-Archiven, die
Befehle update und push, verify mit --against-portal sowie den
CI-Checks-Endpunkt. restore braucht keinen API-Key, der Befehl
authentifiziert sich mit der kurzlebigen Lizenz selbst. analyze läuft
lokal und nimmt keinen API-Key entgegen.
Ist CODECHARTER_API_KEY in der Umgebung gesetzt, holt und erneuert die CLI
die kurzlebige Lizenz automatisch vom Portal. Die Befehle update, push,
rules search und verify --against-portal nehmen den Key stattdessen über
ihre Option --api-key entgegen.
Ein Key mit write:rules kann Profil-Entwurfsinhalte über den CLI-Befehl
push speichern. Einen Entwurf veröffentlichen, löschen oder eine Version
archivieren bleiben reine Browser-Aktionen und brauchen immer eine
eingeloggte Sitzung im Portal, unabhängig von den Scopes eines Keys.
Rate-Limits
API-Anfragen ans Portal sind pro Identität limitiert. Jeder API-Key hat sein eigenes Kontingent; Anfragen aus einer eingeloggten Browser-Sitzung zählen stattdessen auf das Benutzerkonto. Die Standardwerte:
- 60 GET-Anfragen pro Minute
- 10 Schreib-Anfragen pro Minute (POST, PUT, PATCH, DELETE)
Lese- und Schreibzugriffe haben getrennte Kontingente. Das Fenster sind feste 60 Sekunden ab der ersten Anfrage; am Ende des Fensters steht wieder das volle Kontingent zur Verfügung. Downloads der CLI-Release-Archive und der Endpunkt für die kurzlebige Lizenz sind nicht limitiert.
Ist ein Kontingent aufgebraucht, antwortet das Portal mit
429 Too Many Requests. Die Antwort enthält einen Retry-After-Header
mit der Anzahl Sekunden bis zum Zurücksetzen des Fensters sowie einen
JSON-Body, der den Wert im Feld retryAfter wiederholt. Warte so
lange und versuche es erneut.
In der Praxis bleibt ein CI-Lauf weit unter diesen Limits, restore macht
nur eine Handvoll Anfragen. Wenn du doch 429 siehst, sind meist viele
parallele Jobs mit demselben Key die Ursache. Cache das
heruntergeladene CLI-Archiv, statt es in jedem Job neu zu laden, und cache
das Bundle-Verzeichnis (.codecharter/cache/) mit dem Lockfile als
Cache-Key, damit wiederholte Läufe gar keine Portal-Aufrufe machen, siehe
Portal-Profile im CI verwenden. Da jeder Key
sein eigenes Kontingent hat, verhindern getrennte Keys für unabhängige
Pipelines außerdem, dass diese sich gegenseitig ausbremsen.
Was passiert beim Trial-Ende
Wenn deine Subscription abgelaufen ist, geben Keys ab dem nächsten Aufruf 402 Payment Required zurück. Der Key bleibt aktiv, aber unbrauchbar. Sobald die Subscription wieder läuft, funktioniert der Key wieder ohne Änderung.
Audit
In der API-Key-Liste siehst du pro Key:
- Name und Key-Präfix (die ersten 12 Zeichen)
- Wann erzeugt
- Wann zuletzt benutzt
- Wann er abläuft
- Aktueller Status (aktiv / widerrufen / abgelaufen)
- Seine Scopes
Du kannst einen Key direkt in der Liste über das Stift-Symbol umbenennen (bis zu 120 Zeichen). Ein abgelaufener Key wird mit 401 abgelehnt, genau wie ein widerrufener.
Wird ein Key nie benutzt, ist das ein Signal, ihn zu widerrufen. Zeigt "zuletzt benutzt" Aktivität, die du nicht erwartest, schau genauer hin, wo der Key im Einsatz ist.
Mehrere Keys parallel
Sinnvoll, wenn du unterschiedliche CI-Setups hast, z.B. einen Key für die Haupt-CI und einen separaten für einen Build-Server in einer isolierten Umgebung. So kannst du einen widerrufen, ohne den anderen zu treffen.
Es gibt derzeit kein hartes Limit für Keys pro Account.