Authentification

La Claude API prend en charge trois méthodes pour authentifier les requêtes :

Les clés API et Workload Identity Federation accordent le même accès aux points de terminaison de la Claude API. Choisissez les clés API pour démarrer rapidement : une clé personnelle pour votre propre développement, ou une clé de compte de service pour tout ce qui est partagé. Passez à Workload Identity Federation lorsque votre charge de travail dispose déjà d'une identité délivrée par la plateforme que vous pouvez fédérer. Utilisez App Attest pour les applications iOS et macOS que vous distribuez aux utilisateurs finaux.

Clés API

Les « API keys » (clés API) sont des secrets statiques que vous générez dans la Claude Console et que vous envoyez à chaque requête dans l'en-tête x-api-key.

Types de clés

Lorsque vous créez une clé, vous choisissez son type, qui détermine ce que la clé peut faire, où elle fonctionne et quand elle cesse de fonctionner :

Les clés personnelles et les clés de compte de service sont adossées à une identité : chacune appartient à un utilisateur ou à un compte de service que votre organisation gère déjà, et chaque requête agit en tant que cette identité. Lorsque cette identité est retirée de l'organisation, la clé cesse de fonctionner. Cela signifie que les clés ne survivront pas accidentellement aux personnes ou aux charges de travail qui les possèdent. Préférez-les aux clés d'espace de travail pour les nouvelles intégrations.

Utilisez une clé personnelle pour votre propre développement et vos scripts. Une clé personnelle partagée agit en tant qu'une seule personne et cesse de fonctionner lorsque celle-ci part. Pour les charges de travail partagées ou automatisées (CI, services de production), demandez à un administrateur de l'organisation de créer un compte de service afin que la charge de travail dispose de sa propre identité.

Les clés API d'espace de travail fonctionnent toujours mais doivent être considérées comme héritées ; les clés adossées à une identité ou Workload Identity Federation sont à privilégier. Pour migrer, consultez Remplacer les clés API d'espace de travail.

Créer et utiliser une clé

• Créer une clé : accédez à Settings → API keys dans la Claude Console et cliquez sur Create key. Nommez la clé et choisissez une expiration. Définissez Linked account sur vous-même pour une clé personnelle, ou sur un compte de service pour une clé partagée entre plusieurs utilisateurs. Vous pouvez également restreindre la clé à un espace de travail spécifique, ce qui vous évite de définir manuellement un ID d'espace de travail dans les requêtes futures.
• Utiliser la clé : définissez l'en-tête x-api-key sur les requêtes HTTP directes, ou définissez la variable d'environnement ANTHROPIC_API_KEY et les SDK clients la récupèrent automatiquement.

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

Stockez les clés API dans un gestionnaire de secrets, effectuez leur rotation périodiquement, et désactivez ou supprimez toute clé que vous soupçonnez d'avoir fuité. Sur la page API keys, Disable est réversible (l'Admin API indique le status de la clé comme "inactive", et Re-enable le ramène à "active"), tandis que Delete est définitif : la clé est archivée et apparaît toujours dans List API Keys avec status: "archived". Les clés expirées peuvent uniquement être supprimées. Vous pouvez également définir une expiration lors de la création d'une clé afin de limiter la durée pendant laquelle un identifiant ayant fuité reste utilisable.

client = Anthropic(api_key="my-anthropic-api-key")
# ou, avec ANTHROPIC_API_KEY défini dans l'environnement :
client = Anthropic()

Sélectionner un espace de travail

Les clés API créées pour un espace de travail spécifique ne fonctionnent que dans cet espace de travail, et les requêtes API utilisant ces clés peuvent omettre l'ID d'espace de travail.

Si votre clé API n'est pas restreinte à un espace de travail, vous devez spécifier l'ID d'espace de travail dans l'en-tête anthropic-workspace-id pour chaque requête. Consultez l'exemple suivant pour savoir comment définir cet en-tête dans une requête ou dans les SDK.

L'Admin API accepte une clé personnelle ou une clé de compte de service uniquement si la clé n'est pas restreinte à un espace de travail spécifique.

Vous pouvez trouver l'ID d'un espace de travail dans la colonne ID de Settings → Workspaces dans la Claude Console, ou en appelant le point de terminaison List Workspaces. Aucun des deux ne liste l'ID de l'espace de travail par défaut : lisez-le depuis l'en-tête de réponse anthropic-workspace-id de toute requête qui s'y exécute (par exemple, une requête effectuée avec une clé d'espace de travail de l'espace de travail par défaut), ou depuis scope.workspace_id sur une telle clé dans List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Requis pour chaque requête avec une clé multi-espaces de travail.
# Omettez extra_headers pour une clé à espace de travail unique.
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)

# Ou définissez-le une fois pour toutes les requêtes de ce client :
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Si une requête effectuée avec une clé qui n'est pas restreinte à un espace de travail omet l'en-tête, l'API renvoie une erreur 400 invalid_request_error :

{
  "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"
}

Une valeur d'en-tête qui n'est pas un ID d'espace de travail valide renvoie une erreur 400 invalid_request_error avec le message anthropic-workspace-id header must be a valid workspace ID. Si l'espace de travail n'existe pas, ou si l'utilisateur ou le compte de service de la clé n'y a pas accès, l'API renvoie une erreur 404 not_found_error avec le message Workspace `<id>` not found., la même réponse que pour tout espace de travail inconnu.

Workload Identity Federation sélectionne quant à lui un espace de travail lors de l'échange de jetons ; consultez la référence WIF pour plus de détails.

Expiration des clés

Lorsque vous créez une clé API depuis la page API keys dans la Claude Console, vous choisissez une expiration : un préréglage (3 heures, 1 jour, 7 jours ou 30 jours), une durée personnalisée, ou Never pour les clés que vous stockez dans un gestionnaire de secrets et dont vous effectuez vous-même la rotation. Si votre organisation dispose d'une politique d'expiration maximale, la Console limite les préréglages et les durées personnalisées au maximum de la politique, et Never n'est pas disponible. Les clés existantes conservent leur comportement actuel ; l'expiration est définie au moment de la création et ne peut pas être modifiée par la suite. Le même choix d'expiration s'applique lorsque vous créez une clé Admin API dans la Claude Console.

Anthropic envoie un e-mail au créateur de la clé à l'approche de l'expiration : 7 jours avant l'expiration pour les clés créées avec une durée de vie d'au moins 14 jours, et 1 jour avant pour les clés avec une durée de vie d'au moins 7 jours. Les clés avec des durées de vie plus courtes expirent sans e-mail d'avertissement.

Après l'expiration d'une clé, les requêtes effectuées avec celle-ci renvoient une erreur 401 authentication_error. Créez une nouvelle clé pour rétablir l'accès ; les clés expirées ne peuvent pas être réactivées.

Le tableau des clés API de la Console affiche l'expiration de chaque clé, et l'Admin API indique l'horodatage expires_at de chaque clé sur les points de terminaison List API Keys et Retrieve API Key, afin que vous puissiez auditer les clés et effectuer leur rotation avant qu'elles n'expirent. Le champ vaut null pour les clés sans expiration.

L'expiration limite la durée de vie d'un identifiant ayant fuité, mais elle ne remplace pas une bonne hygiène des secrets. Quelle que soit l'expiration, stockez les clés dans un gestionnaire de secrets et désactivez ou supprimez toute clé que vous soupçonnez d'avoir fuité.

Remplacer les clés API d'espace de travail

Si vous disposez d'une clé d'espace de travail, vous pouvez souhaiter la remplacer par Workload Identity Federation ou par une clé personnelle ou de compte de service. Cela offre une meilleure sécurité et une meilleure observabilité.

Consultez Workload Identity Federation pour plus de détails sur la configuration de Workload Identity Federation, qui est à privilégier par rapport aux clés de longue durée.

Pour remplacer une clé d'espace de travail par une clé personnelle ou de compte de service :

1. Décidez du type de clé. Vos propres outils doivent utiliser une clé personnelle. Une charge de travail partagée ou sans surveillance doit utiliser une clé de compte de service.
2. Créez un compte de service si nécessaire. Vous devrez peut-être demander à un administrateur de l'organisation d'en créer un dans Settings → Service accounts et de l'ajouter à l'espace de travail concerné.
3. Créez la nouvelle clé. Créez-la spécifiquement pour l'espace de travail de l'intégration, sauf si plusieurs espaces de travail sont nécessaires.
4. Déployez la nouvelle clé. Remplacez l'ancienne clé partout où l'intégration la lit, généralement la variable d'environnement ANTHROPIC_API_KEY ou une entrée de gestionnaire de secrets. Pour une clé multi-espaces de travail, envoyez également l'en-tête anthropic-workspace-id comme indiqué dans Sélectionner un espace de travail.
5. Supprimez l'ancienne clé. Vérifiez que les requêtes aboutissent, puis supprimez la clé d'espace de travail sur la page API keys.

Workload Identity Federation

« Workload Identity Federation » (fédération d'identité de charge de travail), ou WIF, permet à une charge de travail de s'authentifier avec un jeton d'identité de courte durée délivré par un « identity provider » (fournisseur d'identité), ou IdP, auquel vous faites déjà confiance, tel qu'AWS IAM, Google Cloud ou tout émetteur OIDC conforme aux standards (tel que GitHub Actions, les comptes de service Kubernetes, SPIFFE, Microsoft Entra ID ou Okta). La charge de travail échange son JWT délivré par l'IdP sur POST /v1/oauth/token contre un jeton d'accès Claude API de courte durée, et le SDK actualise automatiquement ce jeton avant qu'il n'expire. Il n'y a aucune chaîne sk-ant-api... à émettre, distribuer ou faire tourner.

La fédération supprime les clés Claude API de longue durée de votre environnement, ce qui réduit le rayon d'impact d'un identifiant ayant fuité et vous permet de gérer les accès avec les mêmes contrôles IdP que vous utilisez déjà pour les ressources cloud. Elle ne garantit pas, à elle seule, une sécurité de bout en bout : la chaîne de confiance n'est aussi solide que la configuration de votre fournisseur d'identité, et un secret de longue durée situé un cran en amont (par exemple, un identifiant cloud statique capable d'émettre des jetons IdP) peut toujours la compromettre. Associez la fédération aux contrôles de votre fournisseur, tels que les listes d'autorisation d'adresses IP, la MFA et la journalisation d'audit.

Pour configurer la fédération, vous créez trois ressources dans la Claude Console (un compte de service, un émetteur de fédération et une règle de fédération), puis vous pointez votre SDK vers la règle. Consultez Workload Identity Federation pour le guide de configuration complet.

App Attest

App Attest authentifie les applications iOS et macOS qui appellent la Claude API directement depuis l'appareil. Chaque installation prouve qu'elle est une version authentique et non modifiée d'une application que vous avez enregistrée dans la Claude Console, à l'aide du service App Attest d'Apple. Anthropic délivre ensuite à l'appareil un jeton d'accès de courte durée qui facture l'utilisation à votre espace de travail. Les jetons sont restreints à votre espace de travail, expirent après une heure et n'autorisent que les appels à la Messages API.

Pour enregistrer votre application et obtenir un ID client, consultez App Attest pour les applications iOS et macOS.

Étapes suivantes