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

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

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

Mise à jour : 26 minutes ago

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 ordinaire). Les clés API d’administration sont accessibles aux propriétaires d’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é n’a besoin des deux portées que si elle doit effectuer des opérations de lecture et d’écriture.

  • Nous devons actuellement activer un indicateur de fonctionnalité pour que votre organisation ait accès à ces points de terminaison. L’indicateur de fonctionnalité est activé si le point de terminaison existant de liste des projets renvoie external_key_id : 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 activer l’indicateur de fonctionnalité pour vous. Veuillez prendre connaissance des pratiques exemplaires suivantes avant de déployer EKM dans vos projets de production existants.

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

    • Procédez à un déploiement progressif plutôt que d’activer EKM sur 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.

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 API actif ni à aucun espace de travail. Si elle est associée à un projet 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 ce point de terminaison pour vérifier plusieurs éléments :

  • Votre configuration infonuagique externe demeure valide auprès d’OpenAI après vos modifications (vous recevrez une réponse de réussite).

  • 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 durées de vie (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"

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

[Accès restreint] Mettre à jour un projet existant avec un identifiant de clé externe

Il s’agit du même point de terminaison existant de mise à jour de projet, 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 souhaitez utiliser EKM sur tous vos projets API existants, demandez-le à votre responsable de compte et nous activerons l’indicateur de fonctionnalité pour vous. Veuillez prendre connaissance des pratiques exemplaires suivantes avant de déployer EKM dans vos projets de production existants.

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

  • Procédez à un déploiement progressif plutôt que d’activer EKM sur 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
}

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