OpenAI
Cette page a été traduite automatiquement. Afficher l’article original en anglais.

EKM (clés externes) dans l’API de gestion

Gérer les clés externes pour EKM avec l’API de gestion

Mise à jour : 7 days ago

Résumé

Accès

  • Les endpoints EKM sont accessibles dans l’API de gestion au moyen d’une clé d’API d’administration. https://platform.openai.com/settings/organization/admin-keys (n’utilisez pas une clé d’API normale). Les clés d’API d’administration 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 les lister ou les valider. Une même clé n’a besoin des deux portées que si elle doit effectuer des opérations de lecture et d’écriture.

  • Nous devons actuellement activer ces endpoints pour votre organisation au moyen d’un indicateur de fonctionnalité. Vous saurez que l’indicateur de fonctionnalité est activé si external_key_id est 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 au moyen de l’API de gestion.

  • Nous recommandons de créer de nouveaux projets pour vos charges de travail EKM. Toutefois, si vous souhaitez utiliser 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 toutes les fonctionnalités d’API que vous utilisez en production dans votre projet d’API EKM de test

    • Effectuez un déploiement graduel au lieu d’ajouter EKM à 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 : string - toujours « aws »

  • name : string - nom descriptif de votre configuration

  • role_arn : string - l’ARN de rôle qu’OpenAI assumera dans votre environnement infonuagique

  • kms_arn : string - l’ARN du système de gestion des clés pour la clé principale que vous gérez

  • external_id : string - l’ID de votre organisation ou de votre projet d’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 : string - toujours « gcp »,

  • name : string - nom descriptif de votre configuration

  • workload_identity_project_number : string - le numéro à 12 chiffres du projet GCP où vous avez enregistré la Workload Identity d’OpenAI

  • workload_identity_pool_id : string - le pool contenant le fournisseur Workload Identity que vous avez enregistré pour OpenAI

  • workload_identity_provider_id : string - 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 par l’intermédiaire de votre STS GCP

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

  • kms_key_ring_name : string - le trousseau de clés du système de gestion des clés contenant la clé principale que vous gérez

  • kms_key_name : string - le nom de la clé principale du système de gestion des clés

  • kms_key_location : string - la région où se trouve votre clé principale du système de gestion des clés

Si votre KMS se trouve dans un projet GCP différent de celui où vous avez enregistré la Workload Identity d’OpenAI, assurez-vous que le projet contenant la Workload Identity 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"
}'

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 : string - toujours « azure »,

  • name : string - nom descriptif de votre configuration

  • tenant_id : string - l’UUID de votre locataire Azure

  • vault_uri : string - l’URI du coffre Azure contenant la clé principale que vous gérez

  • key_name : string - le 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"
}'

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

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 d’API actif ni espace de travail. Si elle est associée à un projet d’API actif, archivez d’abord ce projet. Si elle est associée à un espace de travail, la clé ne peut pas être supprimée.

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 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": "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 infonuagique externe demeure valide auprès d’OpenAI après vos modifications (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 de 1 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 renvoyée par le fournisseur infonuagique.

endpoints au niveau du projet

Créer un nouveau projet avec un ID 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": "Some Project",
   "external_key_id": "extkey_xxxx"
}'

Exemple de réponse

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "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 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 recommandons de créer de nouveaux projets d’API pour vos charges de travail EKM. Si vous souhaitez utiliser EKM sur tous vos projets d’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 toutes les fonctionnalités d’API que vous utilisez en production dans votre projet d’API EKM de test

  • Effectuez un déploiement graduel au lieu d’ajouter EKM à 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, 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
}

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