Authentifizierung

Die Claude API unterstützt drei Möglichkeiten zur Authentifizierung von Anfragen:

API-Keys und Workload Identity Federation gewähren denselben Zugriff auf die Endpunkte der Claude API. Wähle API-Keys, um schnell loszulegen: einen persönlichen Key für deine eigene Entwicklung oder einen Service-Account-Key für alles, was geteilt wird. Wechsle zu Workload Identity Federation, wenn dein Workload bereits eine von der Plattform ausgestellte Identität besitzt, die du föderieren kannst. Verwende App Attest für iOS- und macOS-Apps, die du an Endnutzer verteilst.

API-Keys

„API keys“ (API-Keys) sind statische Geheimnisse, die du in der Claude Console generierst und bei jeder Anfrage im x-api-key-Header mitsendest.

Key-Typen

Wenn du einen Key erstellst, wählst du seinen Typ, der bestimmt, was der Key tun kann, wo er funktioniert und wann er nicht mehr funktioniert:

Persönliche Keys und Service-Account-Keys sind identitätsgebunden: Jeder gehört einem Nutzer oder Service-Account, den deine Organisation bereits verwaltet, und jede Anfrage handelt als diese Identität. Wenn diese Identität aus der Organisation entfernt wird, funktioniert der Key nicht mehr. Das bedeutet, dass Keys nicht versehentlich die Personen oder Workloads überleben, denen sie gehören. Bevorzuge sie gegenüber Workspace-Keys für neue Integrationen.

Verwende einen persönlichen Key für deine eigene Entwicklung und deine Skripte. Ein geteilter persönlicher Key handelt als eine einzige Person und funktioniert nicht mehr, wenn diese die Organisation verlässt. Für geteilte oder automatisierte Workloads (CI, Produktionsdienste) lass einen Organisationsadministrator einen Service-Account erstellen, damit der Workload seine eigene Identität hat.

Workspace-API-Keys funktionieren weiterhin, sollten aber als veraltet betrachtet werden; identitätsgebundene Keys oder Workload Identity Federation werden bevorzugt. Zur Migration siehe Workspace-API-Keys ersetzen.

Einen Key erstellen und verwenden

• Einen Key erstellen: Gehe in der Claude Console zu Settings → API keys und klicke auf Create key. Benenne den Key und wähle ein Ablaufdatum. Setze Linked account auf dich selbst für einen persönlichen Key oder auf einen Service-Account für einen Key, der von mehreren Nutzern geteilt wird. Du kannst den Key auch auf einen bestimmten Workspace beschränken, wodurch du in zukünftigen Anfragen keine Workspace-ID manuell setzen musst.
• Den Key verwenden: Setze den x-api-key-Header bei direkten HTTP-Anfragen oder setze die Umgebungsvariable ANTHROPIC_API_KEY, und die Client-SDKs übernehmen ihn automatisch.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Speichere API-Keys in einem Secrets-Manager, rotiere sie regelmäßig und deaktiviere oder lösche jeden Key, bei dem du vermutest, dass er geleakt wurde. Auf der API-Keys-Seite ist Disable umkehrbar (die Admin API meldet den status des Keys als "inactive", und Re-enable setzt ihn zurück auf "active"), während Delete dauerhaft ist: Der Key wird archiviert und erscheint weiterhin in List API Keys mit status: "archived". Abgelaufene Keys können nur gelöscht werden. Du kannst beim Erstellen eines Keys auch ein Ablaufdatum festlegen, um zu begrenzen, wie lange geleakte Anmeldedaten nutzbar bleiben.

client = Anthropic(api_key="my-anthropic-api-key")
# oder, wenn ANTHROPIC_API_KEY in der Umgebung gesetzt ist:
client = Anthropic()

Einen Workspace auswählen

API-Keys, die für einen bestimmten Workspace erstellt wurden, funktionieren nur in diesem Workspace, und API-Anfragen mit diesen Keys können die Workspace-ID weglassen.

Wenn dein API-Key nicht auf einen Workspace beschränkt ist, musst du bei jeder Anfrage die Workspace-ID im anthropic-workspace-id-Header angeben. Das folgende Beispiel zeigt, wie du diesen Header in einer Anfrage oder in den SDKs setzt.

Die Admin API akzeptiert einen persönlichen Key oder Service-Account-Key nur, wenn der Key nicht auf einen bestimmten Workspace beschränkt ist.

Du findest die ID eines Workspace in der Spalte ID unter Settings → Workspaces in der Claude Console oder durch Aufruf des Endpunkts List Workspaces. Keiner der beiden listet die ID des Default Workspace auf: Lies sie aus dem anthropic-workspace-id-Antwort-Header einer beliebigen Anfrage, die dort ausgeführt wird (zum Beispiel einer, die mit einem Workspace-Key aus dem Default Workspace gestellt wurde), oder aus scope.workspace_id eines solchen Keys in List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Bei jeder Anfrage für einen Multi-Workspace-Key erforderlich.
# Lass extra_headers bei einem Single-Workspace-Key weg.
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# Oder setze es einmal für jede Anfrage dieses Clients:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Wenn eine Anfrage mit einem Key, der nicht auf einen Workspace beschränkt ist, den Header weglässt, gibt die API einen 400 invalid_request_error zurück:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Ein Header-Wert, der keine gültige Workspace-ID ist, gibt einen 400 invalid_request_error mit der Meldung anthropic-workspace-id header must be a valid workspace ID. zurück. Wenn der Workspace nicht existiert oder der Nutzer bzw. Service-Account des Keys keinen Zugriff darauf hat, gibt die API einen 404 not_found_error mit der Meldung Workspace `<id>` not found. zurück, dieselbe Antwort wie für jeden unbekannten Workspace.

Workload Identity Federation wählt stattdessen beim Token-Austausch einen Workspace aus; Details findest du in der WIF-Referenz.

Ablauf von Keys

Wenn du einen API-Key auf der API-Keys-Seite in der Claude Console erstellst, wählst du ein Ablaufdatum: eine Voreinstellung (3 Stunden, 1 Tag, 7 Tage oder 30 Tage), eine benutzerdefinierte Dauer oder Never für Keys, die du in einem Secrets-Manager speicherst und selbst rotierst. Wenn deine Organisation eine Richtlinie für die maximale Gültigkeitsdauer hat, begrenzt die Console Voreinstellungen und benutzerdefinierte Dauern auf das Richtlinienmaximum, und Never ist nicht verfügbar. Bestehende Keys behalten ihr aktuelles Verhalten; das Ablaufdatum wird bei der Erstellung festgelegt und kann danach nicht geändert werden. Dieselbe Auswahl des Ablaufdatums gilt, wenn du in der Claude Console einen Admin-API-Key erstellst.

Anthropic sendet dem Ersteller des Keys eine E-Mail, wenn das Ablaufdatum näher rückt: 7 Tage vor Ablauf für Keys, die mit einer Lebensdauer von mindestens 14 Tagen erstellt wurden, und 1 Tag vorher für Keys mit einer Lebensdauer von mindestens 7 Tagen. Keys mit kürzerer Lebensdauer laufen ohne Warn-E-Mail ab.

Nachdem ein Key abgelaufen ist, geben Anfragen mit ihm einen 401 authentication_error zurück. Erstelle einen neuen Key, um den Zugriff wiederherzustellen; abgelaufene Keys können nicht reaktiviert werden.

Die API-Keys-Tabelle in der Console zeigt das Ablaufdatum jedes Keys, und die Admin API meldet den expires_at-Zeitstempel jedes Keys über die Endpunkte List API Keys und Retrieve API Key, sodass du Keys prüfen und rotieren kannst, bevor sie ablaufen. Das Feld ist null für Keys ohne Ablaufdatum.

Ein Ablaufdatum begrenzt die Lebensdauer geleakter Anmeldedaten, ist aber kein Ersatz für sorgfältigen Umgang mit Geheimnissen. Unabhängig vom Ablaufdatum solltest du Keys in einem Secrets-Manager speichern und jeden Key deaktivieren oder löschen, bei dem du vermutest, dass er geleakt wurde.

Workspace-API-Keys ersetzen

Wenn du einen Workspace-Key hast, möchtest du ihn möglicherweise durch Workload Identity Federation oder einen persönlichen Key bzw. Service-Account-Key ersetzen. Das bietet bessere Sicherheit und Beobachtbarkeit.

Siehe Workload Identity Federation für Details zur Konfiguration von Workload Identity Federation, die gegenüber langlebigen Keys bevorzugt wird.

So ersetzt du einen Workspace-Key durch einen persönlichen Key oder Service-Account-Key:

1. Lege den Key-Typ fest. Dein eigenes Tooling sollte einen persönlichen Key verwenden. Ein geteilter oder unbeaufsichtigter Workload sollte einen Service-Account-Key verwenden.
2. Erstelle einen Service-Account, falls nötig. Möglicherweise musst du einen Organisationsadministrator bitten, einen unter Settings → Service accounts zu erstellen und ihn zum entsprechenden Workspace hinzuzufügen.
3. Erstelle den neuen Key. Erstelle ihn speziell für den Workspace der Integration, sofern nicht mehrere Workspaces benötigt werden.
4. Stelle den neuen Key bereit. Ersetze den alten Key überall, wo die Integration ihn liest, typischerweise in der Umgebungsvariable ANTHROPIC_API_KEY oder einem Eintrag im Secrets-Manager. Sende bei einem Multi-Workspace-Key zusätzlich den anthropic-workspace-id-Header, wie unter Einen Workspace auswählen gezeigt.
5. Lösche den alten Key. Vergewissere dich, dass Anfragen erfolgreich sind, und lösche dann den Workspace-Key auf der API-Keys-Seite.

Workload Identity Federation

„Workload Identity Federation“ (Workload-Identitätsföderation), oder WIF, ermöglicht es einem Workload, sich mit einem kurzlebigen Identitätstoken zu authentifizieren, das von einem „identity provider“ (Identitätsanbieter), oder IdP, ausgestellt wird, dem du bereits vertraust, etwa AWS IAM, Google Cloud oder einem beliebigen standardkonformen OIDC-Aussteller (wie GitHub Actions, Kubernetes-Service-Accounts, SPIFFE, Microsoft Entra ID oder Okta). Der Workload tauscht sein vom IdP ausgestelltes JWT bei POST /v1/oauth/token gegen ein kurzlebiges Zugriffstoken für die Claude API ein, und das SDK erneuert dieses Token automatisch, bevor es abläuft. Es gibt keinen sk-ant-api...-String, der erzeugt, verteilt oder rotiert werden muss.

Föderation entfernt langlebige Claude-API-Keys aus deiner Umgebung, was den Schadensradius geleakter Anmeldedaten verkleinert und es dir ermöglicht, den Zugriff mit denselben IdP-Kontrollen zu verwalten, die du bereits für Cloud-Ressourcen verwendest. Sie garantiert für sich allein keine Ende-zu-Ende-Sicherheit: Die Vertrauenskette ist nur so stark wie die Konfiguration deines Identitätsanbieters, und ein langlebiges Geheimnis einen Schritt weiter oben (zum Beispiel statische Cloud-Anmeldedaten, die IdP-Tokens erzeugen können) kann sie dennoch untergraben. Kombiniere Föderation mit den Kontrollen deines Anbieters, etwa IP-Allowlists, MFA und Audit-Logging.

Um Föderation zu konfigurieren, erstellst du drei Ressourcen in der Claude Console (einen Service-Account, einen Föderationsaussteller und eine Föderationsregel) und verweist dann dein SDK auf die Regel. Siehe Workload Identity Federation für die vollständige Einrichtungsanleitung.

App Attest

App Attest authentifiziert iOS- und macOS-Apps, die die Claude API direkt vom Gerät aus aufrufen. Jede Installation weist mithilfe des App-Attest-Dienstes von Apple nach, dass sie ein echter, unveränderter Build einer App ist, die du in der Claude Console registriert hast. Anthropic stellt dem Gerät dann ein kurzlebiges Zugriffstoken aus, das die Nutzung deinem Workspace in Rechnung stellt. Tokens sind auf deinen Workspace beschränkt, laufen nach einer Stunde ab und autorisieren nur Aufrufe der Messages API.

Um deine App zu registrieren und eine Client-ID zu erhalten, siehe App Attest für iOS- und macOS-Apps.

Nächste Schritte