Authentifizierung

Die Claude API unterstützt drei Möglichkeiten, Anfragen zu authentifizieren:

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

API-Keys

API-Keys sind statische Geheimnisse, die du in der Claude Console generierst und bei jeder Anfrage als Bearer-Token im Authorization-Header sendest.

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 aufhört zu funktionieren:

Persönliche Keys und Service-Account-Keys sind identitätsgebunden: Jeder gehört zu einem Benutzer 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 die Personen oder Workloads, denen sie gehören, nicht versehentlich überdauern. Bevorzuge sie bei neuen Integrationen gegenüber Workspace-Keys.

Verwende einen persönlichen Key für deine eigene Entwicklung und Skripte. Ein geteilter persönlicher Key agiert als eine Person und funktioniert nicht mehr, wenn diese geht. Lass für geteilte oder automatisierte Workloads (CI, Produktionsdienste) 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ätsgestützte Keys oder Workload Identity Federation werden bevorzugt. Zum Migrieren siehe Workspace-API-Keys ersetzen.

Einen Key erstellen und verwenden

• Einen Key erstellen: Gehe in der Claude Console zur Seite API keys (platform.claude.com/settings/keys) und klicke auf Create key. Benenne den Key und wähle ein Ablaufdatum. Setze Linked account für einen persönlichen Key auf dich selbst oder für einen Key, der von mehreren Benutzern geteilt wird, auf einen Service-Account. Du kannst den Key auch auf einen bestimmten Workspace beschränken, wodurch du in zukünftigen Anfragen keine Workspace-ID manuell festlegen musst.
• Den Key verwenden: Sende ihn bei direkten HTTP-Anfragen als Authorization: Bearer <key> oder setze die Umgebungsvariable ANTHROPIC_API_KEY, dann übernimmt das Client-SDK ihn automatisch.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Der veraltete x-api-key: YOUR_API_KEY-Header wird weiterhin anstelle von Authorization unterstützt.

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 Seite API keys in der Claude Console ist Disable umkehrbar (die Admin API meldet den status des Keys als "inactive", und Re-enable setzt ihn wieder 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 verwendbar bleiben.

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

Einen Workspace auswählen

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

Wenn dein API-Key nicht auf einen Workspace beschränkt ist, musst du die Workspace-ID bei jeder Anfrage im Header anthropic-workspace-id angeben. Im folgenden Beispiel siehst du, wie du diesen Header in einer Anfrage oder im SDK 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.

Die ID eines Workspace findest du in der Spalte ID auf der Seite Workspaces (platform.claude.com/settings/workspaces) in der Claude Console oder durch Aufruf des Endpunkts List Workspaces. List Workspaces enthält den Default Workspace nur, wenn du include_default=true übergibst; seine ID steht außerdem im Antwort-Header anthropic-workspace-id jeder Anfrage, die dort ausgeführt wird.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Bei jeder Anfrage erforderlich, wenn der Key nicht auf einen Workspace beschränkt ist.
# Lass extra_headers bei einem Key weg, der auf einen Workspace beschränkt ist.
message = client.messages.create(
    model="claude-opus-5-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 von diesem Client:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This API key is not scoped to a workspace, so this request must include the anthropic-workspace-id header with the ID of the workspace to use. Add the header, or use an API key that is scoped to a workspace."
  },
  "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 oder 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 einen Workspace beim Token-Austausch aus; siehe die WIF-Referenz für Details.

Key-Ablauf

Wenn du einen API-Key auf der Seite API keys 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 ein maximales Ablaufdatum hat, begrenzt die Console Voreinstellungen und benutzerdefinierte Dauern auf das Maximum der Richtlinie, und Never ist nicht verfügbar. Bestehende Keys behalten ihr aktuelles Verhalten; das Ablaufdatum wird bei der Erstellung festgelegt und kann danach nicht mehr geändert werden. Dieselbe Wahl des Ablaufdatums gilt, wenn du in der Claude Console einen Admin-API-Key erstellst.

Anthropic sendet dem Ersteller des Keys eine E-Mail, wenn sich der Ablauf nähert: 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ürzeren Lebensdauern laufen ohne Warn-E-Mail ab.

Nachdem ein Key abgelaufen ist, geben damit gestellte Anfragen 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 die Ablaufzeit jedes Keys, und die Admin-API meldet den expires_at-Zeitstempel jedes Keys an den Endpunkten 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 Ablaufzeit.

Die Ablaufzeit begrenzt die Lebensdauer eines geleakten Anmeldedatums, ist aber kein Ersatz für Geheimnishygiene. Unabhängig von der Ablaufzeit solltest du Keys in einem Secrets-Manager speichern und jeden Key deaktivieren oder löschen, bei dem du einen Leak vermutest.

Workspace-API-Keys ersetzen

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

Details zur Konfiguration von Workload Identity Federation, die gegenüber langlebigen Keys bevorzugt wird, findest du in der WIF-Referenz.

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

1. Entscheide den Key-Typ. Dein eigenes Tooling sollte einen persönlichen Key verwenden. Ein geteilter oder unbeaufsichtigter Workload sollte einen Service-Account-Key verwenden.
2. Erstelle bei Bedarf einen Service-Account. Möglicherweise musst du einen Organisationsadministrator bitten, einen auf der Seite Service accounts (platform.claude.com/settings/service-accounts) in der Claude Console zu erstellen und ihn zum relevanten Workspace hinzuzufügen.
3. Erstelle den neuen Key. Erstelle ihn speziell für den Workspace der Integration, es sei denn, die Integration benötigt mehrere Workspaces.
4. Stelle den neuen Key bereit. Ersetze den alten Key überall, wo die Integration ihn ausliest, typischerweise die Umgebungsvariable ANTHROPIC_API_KEY oder einen Eintrag in einem Secrets-Manager. Bei einem Key, der nicht auf einen Workspace beschränkt ist, sende außerdem den Header anthropic-workspace-id, 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 in der Claude Console.

Workload Identity Federation

Workload Identity Federation (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. Zu solchen IdPs gehören AWS IAM, Google Cloud und jeder standardkonforme 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 Claude-API-Zugriffstoken ein, und das SDK aktualisiert dieses Token automatisch, bevor es abläuft. Es gibt keinen sk-ant-api...-String, der erstellt, verteilt oder rotiert werden muss.

Föderation entfernt langlebige Claude-API-Keys aus deiner Umgebung, was den Schaden begrenzt, den geleakte Anmeldedaten verursachen können, und ermöglicht dir, den Zugriff mit denselben IdP-Kontrollen zu verwalten, die du bereits für Cloud-Ressourcen verwendest. Sie garantiert für sich allein jedoch keine durchgängige Sicherheit: Die Vertrauenskette ist nur so stark wie die Konfiguration deines Identitätsanbieters, und ein langlebiges Secret einen Schritt früher in dieser Kette (zum Beispiel statische Cloud-Anmeldedaten, mit denen IdP-Tokens erstellt werden können) kann sie dennoch untergraben. Kombiniere Föderation mit den Kontrollen deines Anbieters, wie IP-Allowlists, MFA und Audit-Logging.

Um Federation zu konfigurieren, erstellst du drei Ressourcen in der Claude Console (einen Service-Account, einen Federation-Aussteller und eine Federation-Regel) und richtest dann dein SDK auf die Regel aus. 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 von Apples App-Attest-Dienst 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 1 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