EKM (External Keys) dans l'API de gestion

Découvrez comment gérer les clés externes pour EKM à l’aide de l’API de gestion.

Dernière mise à jour : 18 hours ago

Résumé

Accès

  • Les points de terminaison EKM sont accessibles dans l’API Management via une clé API Admin. https://platform.openai.com/settings/organization/admin-keys (n’utilisez pas une clé API normale). Les clés API Admin sont disponibles pour les 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 répertorier, récupérer ou valider des clés externes. Une seule clé a besoin des deux portées uniquement si elle doit effectuer des opérations de lecture et d’écriture.

Utilisation

Restrictions

  • Vous devez d'abord tester EKM sur un nouveau projet via l'API de gestion.

  • Nous vous recommandons de créer de nouveaux projets pour vos charges de travail EKM. Veuillez prendre connaissance 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 d’API EKM de test.

    • Appliquez un déploiement progressif plutôt que de renseigner EKM sur tous les projets d’API de production en une seule fois.

Endpoint au niveau de l'organisation

Enregistrer une clé externe pour votre organisation

AWS

Exemple de requête  :

  • type: string - always “aws”

  • name : chaîne de caractères - Un nom convivial pour votre configuration

  • role_arn : chaîne - L'ARN du rôle qu'OpenAI assumera dans votre cloud

  • kms_arn : chaîne de caractères - ARN du système de gestion des clés pour la clé principale que vous gérez

  • external_id : chaîne de caractères - l'identifiant de votre organisation ou de votre 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>"
}'

Réponse d’exemple :

{
"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: string - always "gcp",

  • name : chaîne de caractères - Un nom convivial pour votre configuration

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

  • workload_identity_pool_id : chaîne - Le pool qui contient le fournisseur d'identité de charge de travail que vous avez enregistré pour OpenAI

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

  • audience : string - L'audience qu'OpenAI doit transmettre dans le token lorsque nous assumons un rôle via votre GCP STS

  • kms_project_id : string - Le nom du projet GCP où se trouve votre KMS

  • kms_key_ring_name : chaîne de caractères - le trousseau de clés du système de gestion des clés contenant la clé maître que vous gérez

  • kms_key_name : chaîne de caractères - Nom de la clé maître 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 se trouve dans un projet GCP différent de celui dans lequel vous avez enregistré l’identité de charge de travail d’OpenAI, assurez-vous que le projet qui contient l’identité de charge de travail d’OpenAI a au moins activé KMS 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"
}'

Réponse d’exemple :

{
"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: string - always "azure",

  • name : chaîne de caractères - Un nom convivial pour votre configuration

  • tenant_id : chaîne de caractères - UUID de votre locataire Azure

  • vault_uri : chaîne de caractères - URI du coffre Azure contenant la clé principale que vous gérez

  • key_name : de caractères - Nom de la clé principale Azure Key Vault que vous gérez.

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

Réponse d’exemple :

{
"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 à OpenAI l’accès. La clé doit comporter une balise openai_organization_id en texte libre dont la valeur est votre identifiant d’organisation OpenAI. Pour connaître les étapes de configuration, consultez : configuration d’OCI Vault pour la gestion des clés d’entreprise.

Exemple de requête :

  • type : chaîne de caractères - toujours « oci »

  • objectif : chaîne - "ekm" ; valeur par défaut en cas d’omission

  • name : chaîne de caractères - Un nom convivial pour votre configuration

  • région : chaîne - La région OCI qui contient votre coffre-fort 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>"
}'

Réponse d’exemple :

{
"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. Enregistrez l’identifiant renvoyé et utilisez-le 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 également aux enregistrements OCI.

Pour la récupération PSP, utilisez une inscription RSA-3072 distincte avec l’objectif : "psp_decryption" et un key_version_ocid exact. Définissez psp_decryption_key_id sur l’identifiant d’inscription OpenAI correspondant. OpenAI n’a besoin que 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 les clés asymétriques — OCI Vault.

Supprimer une clé externe enregistrée dans votre organisation

Remarque : la suppression est bloquée tant qu’un projet actif ou un espace de travail utilise l’inscription. Pour EKM, archivez d’abord les projets API associés ; une inscription EKM associée à un espace de travail reste protégée. Pour la récupération PSP, remplacez ou effacez psp_decryption_key_id dans chaque projet actif qui fait référence à l’inscription avant de la supprimer. La suppression d’une inscription OpenAI ne supprime pas la clé cloud.

Exemple de requête

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

Réponse d’exemple

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

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

Sans filtre de finalité, la liste inclut à la fois les enregistrements de récupération EKM et PSP. Utilisez ?purpose=ekm ou ?purpose=psp_decryption pour filtrer par finalité.

Exemple de requête

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

Réponse d’exemple

{
"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é cloud.

  • Pour EKM, OpenAI vérifie qu’elle peut chiffrer et déchiffrer à l’aide de la clé. Pour le comportement de révocation et de mise en cache, consultez : les recommandations 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 déchiffrer les données. Un échec de validation ne supprime ni ne remplace l’instantané stocké de la clé publique.

La récupération d’un enregistrement avec GET renvoie la configuration enregistrée et ne vérifie pas à nouveau l’accès à votre clé cloud.

Exemple de requête

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

Réponse d’exemple

{
"status": "success"
}

Ou, une erreur s'est produite du fournisseur de cloud.

Points de terminaison au niveau du projet

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

Il s'agit du même endpoint que celui existant pour la 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"
}'

Réponse d’exemple

{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}

Mettez à 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 vous recommandons de créer de nouveaux projets API pour vos charges de travail EKM. Veuillez prendre connaissance 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 d’API EKM de test.

  • Appliquez un déploiement progressif plutôt que de renseigner EKM sur tous les projets d’API de production en une seule 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"
}'

Répertoriez tous les projets de votre organisation

Il s’agit du même point de terminaison que le 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"

Réponse d’exemple

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

Cet article vous a-t-il été utile ?