Résumé
Accès
Les points de terminaison EKM sont accessibles dans l’API de gestion au moyen d’une clé API d’administration. https://platform.openai.com/settings/organization/admin-keys (n’utilisez pas de clé API standard). Les clés API d’administration sont accessibles aux propriétaires d’organisation.
Utilisez
api.external_keys.writepour créer ou supprimer des clés externes, etapi.external_keys.readpour lister, récupérer ou valider des clés externes. Une même clé n’a besoin des deux portées que si elle doit effectuer des opérations de lecture et d’écriture.
Utilisation
Votre configuration EKM est enregistrée au niveau de l’organisation au moyen d’un nouveau point de terminaison https://api.openai.com/v1/organization/external_keys.
L’enregistrement de votre configuration EKM renvoie 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 de la requête au point de terminaison existant de création de projet https://api.openai.com/v1/organization/projects.
Restrictions
Vous devez d’abord tester EKM dans un nouveau projet au moyen de l’API de gestion.
Nous recommandons de créer de nouveaux projets pour vos charges de travail EKM. Veuillez tenir compte des bonnes pratiques suivantes avant de déployer EKM dans vos projets de production existants.
Testez d’abord toutes les fonctionnalités de l’API que vous utilisez en production dans votre projet API EKM de test.
Procédez à un déploiement progressif plutôt que d’activer EKM dans tous les projets API de production à la fois.
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 - L’ARN du rôle qu’OpenAI assumera dans votre environnement infonuagique
kms_arn : chaîne - L’ARN du système de gestion des clés pour la clé principale que vous gérez
external_id : chaîne - Votre identifiant d’organisation ou 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": "AWS EKM Config",
"role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}'Exemple de réponse :
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}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 du projet GCP dans lequel 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 jeton lorsque nous assumons un rôle par l’intermédiaire de votre STS GCP
kms_project_id: chaîne - Le nom du projet GCP qui héberge votre KMS
kms_key_ring_name : chaîne - Le trousseau du système de gestion des clés contenant la clé principale que vous gérez
kms_key_name : chaîne - Le nom de la clé principale du système de gestion des clés
kms_key_location : chaîne - La région où se trouve la clé principale de votre système de gestion des clés
Si votre KMS est hébergé dans un projet GCP différent de celui où vous avez enregistré l’identité Workload Identity d’OpenAI, assurez-vous que KMS est au moins activé dans le projet contenant l’identité Workload Identity d’OpenAI en accédant à 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": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role",
"audience": "<your org id or project id>",
"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": "GCP EKM Config",
"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": "<your org id or project id>",
"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é principale que vous gérez
key_name : chaîne - Le nom de la clé principale Azure Key Vault que vous gérez.
Il doit être de la forme <org-xxx>--<any_name>
où org-xxx est votre identifiant d’organisation OpenAI, que vous pouvez trouver à l’adresse 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": "Azure EKM Config",
"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": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}OCI
Configurez une clé AES-256 activée et accordez-y l’accès à OpenAI. La clé doit comporter une balise à format libre openai_organization_id dont la valeur est votre identifiant d’organisation OpenAI. Pour les étapes de configuration, consultez : Configurer OCI Vault pour la gestion des clés d’entreprise.
Exemple de requête :
type : chaîne - toujours "oci"
purpose : chaîne - "ekm"; valeur par défaut si omis
name : chaîne - Un nom convivial pour votre configuration
region : chaîne - La région OCI contenant votre coffre et votre clé
vault_ocid : chaîne - L’OCID complet de votre coffre
key_ocid : chaîne - L’OCID complet de votre clé AES-256
Ne transmettez pas key_version_ocid pour EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Exemple de réponse :
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}L’API renvoie HTTP 200 en cas de réussite. Conservez la valeur id renvoyée et utilisez-la comme external_key_id lors de la création d’un projet. Les opérations existantes de listage, de récupération, de validation et de suppression s’appliquent aussi aux enregistrements OCI.
Pour la récupération PSP, utilisez un enregistrement RSA-3072 distinct avec purpose: "psp_decryption" et un key_version_ocid exact. Définissez psp_decryption_key_id sur son identifiant d’enregistrement OpenAI. OpenAI a seulement besoin d’un accès en lecture aux métadonnées et aux clés publiques de cette clé RSA. Pour la configuration complète, consultez : Configurer des clés asymétriques — OCI Vault.
Supprimer une clé externe enregistrée auprès de votre organisation
Remarque : La suppression est bloquée tant qu’un projet ou un espace de travail actif utilise l’enregistrement. Pour EKM, archivez d’abord les projets API associés; un enregistrement EKM associé à un espace de travail demeure protégé. Pour la récupération PSP, remplacez ou effacez psp_decryption_key_id dans chaque projet actif qui fait référence à l’enregistrement avant de supprimer ce dernier. La suppression d’un enregistrement OpenAI ne supprime pas la clé infonuagique.
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": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}Obtenir les clés externes enregistrées auprès de votre organisation
Sans filtre sur le paramètre purpose, la liste comprend les enregistrements EKM et ceux de récupération PSP. Utilisez ?purpose=ekm ou ?purpose=psp_decryption pour filtrer selon l’usage.
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": "AWS EKM Config",
"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
Utilisez la validation pour vérifier qu’OpenAI peut toujours accéder à votre clé infonuagique.
Pour EKM, OpenAI vérifie qu’il est possible de chiffrer et de déchiffrer avec la clé. Pour le fonctionnement de la révocation et de la mise en cache, consultez : les directives sur le cycle de vie des clés.
Pour la récupération PSP, OpenAI récupère la clé publique de la version enregistrée et la compare à l’instantané stocké. Une validation réussie ne confirme pas que votre identité de récupération peut effectuer le déchiffrement. Une validation échouée ne supprime ni ne remplace l’instantané de clé publique stocké.
La récupération d’un enregistrement avec GET renvoie la configuration stockée sans vérifier de nouveau l’accès à votre clé infonuagique.
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 renvoyée par le fournisseur infonuagique.
endpoints au niveau du projet
Créer un nouveau projet avec un identifiant de clé externe
Il s’agit du même point de terminaison existant de création de projet, 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": "Some Project",
"external_key_id": "extkey_xxxx"
}'Exemple de réponse
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Mettre à jour un projet existant avec un identifiant de clé externe
Il s’agit du même point de terminaison de mise à jour de projet 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. Veuillez tenir compte des bonnes pratiques suivantes avant de déployer EKM dans vos projets de production existants.
Testez d’abord toutes les fonctionnalités de l’API que vous utilisez en production dans votre projet API EKM de test.
Procédez à un déploiement progressif plutôt que d’activer EKM dans tous les projets API de production à la fois.
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 point de terminaison existant, 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": "Project Name",
"external_key_id": "extkey_xxxx",
"created_at": 1717798982,
"archived_at": null,
"status": "active"
}
],
"first_id": "proj_xxxx",
"last_id": "proj_xxxx",
"has_more": true
}