OpenAI

EKM (External Keys) dans l'API de gestion

Gérez les clés externes pour EKM à l'aide de l'API de gestion

Dernière mise à jour : 4 days ago

Résumé

Accès

  • Les endpoints EKM sont accessibles dans l' API Management via une Admin API Key. 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 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.

  • Nous devons actuellement activer via un feature flag l'accès de votre organisation à ces endpoints. Vous savez que vous avez le drapeau de fonctionnalité si vous voyez **external_key_id **renvoyé par l'endpoint List Projects existant : https://api.openai.com/v1/organization/projects

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. Néanmoins, si vous souhaitez utiliser EKM sur un projet existant, nous pouvons vous ajouter au drapeau de fonctionnalité. 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 : chaîne - toujours « aws »

  • name : string - 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 - toujours « 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 à 12 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 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 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 : chaîne de caractères - toujours « 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 : string - 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" : "Configuration EKM Azure",
  "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"
}

Supprimer une clé externe enregistrée dans votre organisation

Remarque : Vous ne pouvez supprimer une clé externe que si elle n'est associée à aucun projet actif. S'il est associé à 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"

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

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

Vous pouvez utiliser cet endpoint pour vérifier plusieurs éléments

  • Votre configuration cloud externe reste valide avec OpenAI après avoir apporté des modifications (vous recevrez une réponse de confirmation).

  • La révocation de votre clé a été effectuée correctement, est en cours de traitement par OpenAI et prendra effet après l'expiration des TTL du cache d'une heure (vous recevrez 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"

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" : "Un projet",
   "external_key_id" : "extkey_xxxx"
}'

Réponse d'exemple

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

[Limité] Mettre à jour un projet existant avec un ID 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. Si vous souhaitez activer EKM sur tous vos projets API existants, contactez votre directeur de compte et nous vous ajouterons au drapeau de fonctionnalité. 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

C'est le même endpoint que l'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"

Réponse d'exemple

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

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