API-Schlüssel und Access-Token

Ein API-Key ist der Zugang deiner Programme zur LinkHarbor-API. Er gehört zu einem Workspace, nicht zu einer Person, und darf genau das, was du ihm über Scopes erlaubst. Für den eigentlichen Aufruf tauschst du den Key gegen ein kurzlebiges Access-Token.

#Wer darf API-Keys anlegen?

• Eigentümer und Admins des Workspaces – Editoren und Viewer sehen unter „Callback & API“ nur die Karte „Verbundene Apps“
• Ab Creator Pro; in Creator Free zeigt die Karte „API-Keys sind ab Creator Pro verfügbar.“
• Gleichzeitig aktiv: bis zu 5 Keys in Creator Pro, bis zu 20 in Creator Agency, bis zu 50 in Enterprise

Ist das Limit erreicht, schlägt das Anlegen mit 409 limit_reached fehl. Lösch dann zuerst einen Key, den du nicht mehr brauchst.

#API-Key anlegen

1. Öffne in der Navigation „Callback & API“
2. Klicke in der Karte „API-Keys“ auf „+ Neuen Key erstellen“
3. Gib unter „Name (optional)“ einen Namen ein, an dem du den Key später erkennst, zum Beispiel „CI/CD Pipeline“ oder „Shop-Sync“
4. Wähle unter „Scopes“ pro Bereich „Lesen“ oder „Schreiben“
5. Klicke auf „Key erstellen“
6. Kopiere das „Key-Secret (geheim)“ sofort und speichere es sicher
7. Schließe den Dialog – die Key-ID findest du jederzeit in der Liste

„Name (optional)“

Bis zu 64 Zeichen. Ohne Namen heißt der Key in der Liste „API-Key #ID“.

„Scopes“

Mindestens einer ist Pflicht. „Schreiben“ schließt „Lesen“ desselben Bereichs automatisch ein. Statistiken und Unterstützungen gibt es nur lesend, Workspace-Templates nur schreibend. Alle Scopes erklärt Scopes im Detail.

„Key-Secret (geheim)“

Beginnt mit lt_ und wird genau einmal angezeigt („⚠️ Nur einmalig sichtbar — jetzt kopieren!“). LinkHarbor speichert nur einen Hash davon und kann es dir später nicht mehr zeigen.

„Key-ID:“

16 Zeichen aus Ziffern und Großbuchstaben A–F, zum Beispiel 6F668EA6598B0692. Sie ist nicht geheim und steht mit Kopier-Button in der Liste.

#Die Liste der Keys

Jeder aktive Key zeigt Name, Status „Aktiv“, Key-ID, Scopes, „Erstellt:“ und „Zuletzt:“ bzw. „Noch nicht genutzt“. Der Zeitpunkt der letzten Nutzung wird bei jedem Aufruf mit dem Key aktualisiert, höchstens einmal pro Minute. Mit „↺ Aktualisieren“ lädst du die Liste neu.

#Key gegen ein Access-Token tauschen

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

Das Access-Token. Du schickst es bei jeder Anfrage als Authorization: Bearer <token>.

expires_in

Gültigkeit in Sekunden: 900, also 15 Minuten. Ein Refresh-Token gibt es nicht – hol dir danach einfach mit Key-ID und Secret ein neues Token.

Das Token steht für den Workspace und trägt genau die Scopes des Keys. Es hat keine Rolle wie eine Person: Endpunkte, die im Dashboard nur Eigentümer und Admins vorbehalten sind (Mitglieder, Abrechnung, Domains verwalten, Webhooks, Workspace-Einstellungen), lehnt die API für Tokens aus API-Keys grundsätzlich ab. Ausnahmen sind Short Links und Workspace-Templates, die mit dem passenden Scope funktionieren, sowie das Lesen der Callback-Secrets (ohne Secret im Klartext) mit read:workspaces.

#Fehlversuche und Sperre

Bei api_key_locked steht die Restzeit in details.retry_after_sec. Ein erfolgreicher Tausch setzt den Zähler zurück.

#Key löschen und wechseln

1. Klicke beim Key auf „Löschen“
2. Tippe zur Bestätigung DELETE ein
3. Klicke auf „Endgültig löschen“

Der Key wird sofort ungültig – auch bereits ausgestellte Access-Tokens funktionieren ab diesem Moment nicht mehr und bekommen 401 invalid_token. Einen Rotieren-Knopf gibt es nicht. Zum Wechseln legst du einen neuen Key an, stellst dein Programm um und löschst danach den alten.

#Wenn der Plan sinkt

Wechselt der Workspace auf Creator Free, werden alle API-Keys widerrufen. Bei einem Wechsel auf einen Plan mit weniger Keys bleiben die neuesten erhalten, die übrigen werden widerrufen. Widerrufene Keys kommen bei einem späteren Upgrade nicht zurück – du legst dann neue an. Eigentümer bekommen eine E-Mail mit der Liste der deaktivierten Funktionen. Mehr unter Kündigen und Downgrade.

#Sicher aufbewahren

• Secret nur in einem Secret-Speicher oder in Umgebungsvariablen ablegen, nie im Quellcode oder Git-Repository
• Nie in Code verwenden, der im Browser oder in einer App beim Nutzer läuft
• Pro Anwendung einen eigenen Key mit möglichst wenigen Scopes anlegen
• Keys, die du nicht mehr brauchst, sofort löschen
• Bei Verdacht auf ein Leck: Key löschen und neu anlegen