Résumé

Accès

• Les endpoints EKM sont accessibles dans l’API de gestion au moyen d’une clé API d’administrateur. https://platform.openai.com/settings/organization/admin-keys (n’utilisez pas une clé API normale). Les clés API d’administrateur sont offertes aux propriétaires de l’organisation.

• Utilisez api.external_keys.write pour créer ou supprimer des clés externes, et api.external_keys.read pour lister ou valider des clés externes. Une même clé a besoin des deux portées seulement si elle doit effectuer à la fois des opérations de lecture et d’écriture.

• À l’heure actuelle, nous devons activer un indicateur de fonctionnalité pour votre organisation afin d’utiliser ces endpoints. Vous saurez que l’indicateur de fonctionnalité est activé si vous voyez **external_key_id ** retourné par le endpoint existant List Projects : https://api.openai.com/v1/organization/projects

Utilisation

• Votre configuration EKM est enregistrée au niveau de l’organisation au moyen d’un nouveau endpoint https://api.openai.com/v1/organization/external_keys

• L’enregistrement de votre configuration EKM retourne un external_key_id sous la forme extkey_xxxx

• Les configurations EKM sont activées au niveau du projet en transmettant un external_key_id dans le corps du endpoint existant Create Project https://api.openai.com/v1/organization/projects

Restrictions

• Vous devez d’abord tester EKM sur un nouveau projet au moyen de l’API de gestion.

• Nous recommandons de créer de nouveaux projets pour vos charges de travail EKM. Toutefois, si vous voulez EKM sur un projet existant, nous pouvons vous ajouter à l’indicateur de fonctionnalité. Veuillez prendre note des pratiques exemplaires suivantes avant de déployer EKM dans vos projets de production existants.

  • Testez d’abord dans votre projet API EKM de test toutes les fonctionnalités d’API que vous utilisez en production

  • Procédez à un déploiement graduel au lieu de renseigner EKM dans tous les projets d’API de production en même temps

Endpoints au niveau de l’organisation

Enregistrer une clé externe dans votre organisation

AWS

Exemple de requête

• type : chaîne - toujours « aws »

• name : chaîne - Un nom convivial pour votre configuration

• role_arn : chaîne - Le Role ARN qu’OpenAI assumera dans votre nuage

• kms_arn : chaîne - Le Key Management System ARN de la clé maîtresse que vous gérez

• external_id : chaîne - Votre identifiant d’organisation ou l’identifiant de projet API

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
  "type": "aws",
  "name": "Configuration EKM AWS",
  "role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <votre identifiant d’organisation ou de projet>
}'

Exemple de réponse

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746175499,
  "api_project_ids": [],
  "type": "aws",
  "name": "Configuration EKM AWS",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <votre identifiant d’organisation ou de projet>
}  

GCP

Exemple de requête

• type : chaîne - toujours "gcp",

• name : chaîne - Un nom convivial pour votre configuration

• workload_identity_project_number : chaîne - Le numéro de projet GCP à 12 chiffres où vous avez enregistré l’identité de charge de travail d’OpenAI

• workload_identity_pool_id : chaîne - Le pool contenant le fournisseur Workload Identity que vous avez enregistré pour OpenAI

• workload_identity_provider_id : chaîne - Le fournisseur Workload Identity que vous avez enregistré pour OpenAI

• audience: chaîne - L’audience qu’OpenAI doit transmettre dans le token lorsque nous assumons un rôle au moyen de votre GCP STS

• kms_project_id: chaîne - Le nom du projet GCP où réside votre KMS

• kms_key_ring_name : chaîne - Le trousseau de clés Key Management System contenant la clé maîtresse que vous gérez

• kms_key_name : chaîne - Le nom de la clé maîtresse Key Management System

• kms_key_location : chaîne - La région où se trouve votre clé maîtresse Key Management System

Si votre KMS se trouve dans un projet GCP différent de celui où vous avez enregistré l’identité de charge de travail d’OpenAI, assurez-vous que le projet contenant l’identité de charge de travail d’OpenAI a au moins KMS activé en allant à https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
   "type": "gcp",
   "name": "Configuration EKM GCP",
   "workload_identity_project_number": "123456789012",
   "workload_identity_pool_id": "openai-azure",
   "workload_identity_provider_id": "openai-ekm-service-role",
   "audience": <votre identifiant d’organisation ou de projet>,
   "kms_project_id": "adjective-noun-12345",
   "kms_key_name": "openai-kms-key",
   "kms_key_ring_name": "openai-kms-key-ring",
   "kms_key_location": "us-east1"
}'

Exemple de réponse

{
  "id": "extkey_xxxxxx",
  "object": "organization.external_key",
  "created_at": 1746174349,
  "api_project_ids": [],
  "type": "gcp",
  "name": "Configuration EKM GCP",
  "workload_identity_project_number": "123456789012",
  "kms_key_ring_name": "openai-kms-key-ring",
  "kms_key_name": "openai-kms-key",
  "kms_key_location": "us-east1",
  "audience": <votre identifiant d’organisation ou de projet>,
  "kms_project_id": "adjective-noun-12345",
  "workload_identity_pool_id": "openai-azure",
  "workload_identity_provider_id": "openai-ekm-service-role"
}

Azure

Exemple de requête

• type : chaîne - toujours "azure",

• name : chaîne - Un nom convivial pour votre configuration

• tenant_id : chaîne - L’UUID de votre locataire Azure

• vault_uri : chaîne - L’URI du coffre Azure contenant la clé maîtresse que vous gérez

• key_name : chaîne - Le nom de la clé maîtresse Azure Key Vault que vous gérez.

  • Elle doit avoir la forme <org-xxx>--<any_name>

  • où org-xxx est votre identifiant d’organisation OpenAI que vous pouvez trouver à https://platform.openai.com/settings/organization/general

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
  "type": "azure",
  "name": "Configuration EKM Azure",
  "tenant_id": "<UUID>",
  "vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
  "key_name": "org-xxx--some-key"
}'

Exemple de réponse

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746174377,
  "api_project_ids": [],
  "type": "azure",
  "name": "Configuration EKM Azure",
  "tenant_id": "<UUID>",
  "vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
  "key_name": "org-xxx--some-key"
}

Supprimer une clé externe enregistrée dans votre organisation

Remarque : Vous pouvez supprimer une clé externe seulement si elle n’est associée à aucun projet actif. Si elle est associée à un projet actif, vous devez d’abord archiver ce projet.

Exemple de requête

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Exemple de réponse

{
  "id": "extkey_xxxxx",
  "object": "organization.external_key.deleted",
  "created_at": 1746127808,
  "api_project_ids": [],
  "type": "aws",
  "account_number": "123456789012",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "name": "Configuration EKM AWS",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

Obtenir les clés externes enregistrées dans votre organisation

Exemple de requête

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Exemple de réponse

{
  "object": "list",
  "data": [
    {
      "id": "extkey_xxxx",
      "object": "organization.external_key",
      "created_at": 1746127808,
      "api_project_ids": [],
      "type": "aws",
      "name": "Configuration EKM AWS",
      "account_number": "123456789012",
      "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  	role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
    }
  ],
  "first_id": "extkey_xxxx",
  "has_more": false,
  "last_id": "extkey_xxxx"
}

Valider une clé externe

Vous pouvez utiliser ce endpoint pour vérifier plusieurs choses

• Votre configuration de nuage externe demeure valide avec OpenAI après avoir apporté des changements (vous verrez une réponse de réussite)

• La révocation de votre clé est effectuée correctement, est en cours de traitement par OpenAI et prendra effet après l’expiration des TTL de cache d’une heure (vous verrez une réponse d’erreur)

Exemple de requête

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Exemple de réponse

{
 "status": "success"
}

Ou une erreur provenant du fournisseur de services infonuagiques.

Endpoints au niveau du projet

Créer un nouveau projet avec un identifiant de clé externe

Il s’agit du même endpoint Create Project existant, avec l’ajout du paramètre external_key_id dans la requête et la réponse.

Exemple de requête

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
   "name": "Un projet",
   "external_key_id": "extkey_xxxx"
}'

Exemple de réponse

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Un projet",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[Restreint] Mettre à jour un projet existant avec un identifiant de clé externe

Il s’agit du même endpoint Update Project existant, avec l’ajout du paramètre external_key_id dans la requête et la réponse.

Nous recommandons de créer de nouveaux projets API pour vos charges de travail EKM. Si vous voulez EKM sur tous vos projets API existants, demandez-le à votre directeur de compte et nous vous ajouterons à l’indicateur de fonctionnalité. Veuillez prendre note des pratiques exemplaires suivantes avant de déployer EKM dans vos projets de production existants.

• Testez d’abord dans votre projet API EKM de test toutes les fonctionnalités d’API que vous utilisez en production

• Procédez à un déploiement graduel au lieu de renseigner EKM dans tous les projets d’API de production en même temps

Exemple de requête

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
   "external_key_id": "extkey_xxxx"
}'

Lister tous les projets de votre organisation

Il s’agit du même endpoint existant, mais avec l’ajout de external_key_id dans la réponse de l’API

Exemple de requête

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Exemple de réponse

{
  "object": "list",
  "data": [
    {
      "object": "organization.project",
      "id": "proj_xxxx",
      "name": "Nom du projet",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}