OpenAI
Esta página se tradujo automáticamente. Ver el artículo original en inglés.

EKM (External Keys) en la API de administración

Gestionar claves externas para EKM con la API de administración

Actualización: 19 days ago

Resumen

Acceso

  • Los endpoints de EKM son accesibles en la API de administración mediante una clave de API de administrador. https://platform.openai.com/settings/organization/admin-keys (no uses una clave de API normal). Las claves de API de administrador están disponibles para los propietarios de la organización.

  • Usa api.external_keys.write para crear o eliminar claves externas, y api.external_keys.read para listar o validar claves externas. Una misma clave solo necesita ambos ámbitos si debe realizar operaciones tanto de lectura como de escritura.

  • Actualmente tenemos que habilitar tu organización en la feature flag de estos endpoints. Sabrás que tienes la feature flag si ves que el endpoint List Projects existente devuelve external_key_id : https://api.openai.com/v1/organization/projects

Uso

Restricciones

  • Primero debes probar EKM en un proyecto nuevo mediante la API de administración.

  • Recomendamos crear nuevos proyectos para tus cargas de trabajo de EKM. No obstante, si quieres usar EKM en un proyecto existente, podemos añadirte a la feature flag. Ten en cuenta las siguientes prácticas recomendadas antes de implantar EKM en tus proyectos de producción existentes.

    • Prueba primero todas las funciones de la API que uses en producción en tu proyecto de API de EKM de prueba

    • Haz una implantación gradual en lugar de aplicar EKM a todos los proyectos de API de producción a la vez

Endpoints a nivel de organización

Registrar una clave externa en tu organización

AWS

Solicitud de ejemplo

  • type: string -  siempre «aws»

  • name: string -  un nombre descriptivo para tu configuración

  • role_arn: string - el ARN del rol que OpenAI asumirá en tu nube

  • kms_arn: string - el ARN del sistema de gestión de claves para la clave maestra que gestionas

  • external_id: string - el ID de tu organización o proyecto de 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>
}'

Respuesta de ejemplo

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

Solicitud de ejemplo

  • type: string - siempre  «gcp»,

  • name: string - un nombre descriptivo para tu configuración

  • workload_identity_project_number: string - el número de proyecto de GCP de 12 dígitos donde registraste la identidad de carga de trabajo de OpenAI

  • workload_identity_pool_id: string - el grupo que contiene el proveedor de Workload Identity que registraste para OpenAI

  • workload_identity_provider_id: string - el proveedor de Workload Identity que registraste para OpenAI

  • audience: string - la audiencia que OpenAI debe pasar en el token cuando asumamos un rol mediante tu STS de GCP

  • kms_project_id: string - el nombre del proyecto de GCP donde reside tu KMS

  • kms_key_ring_name: string - el anillo de claves del sistema de gestión de claves que contiene la clave maestra que gestionas

  • kms_key_name: string - el nombre de la clave maestra del sistema de gestión de claves

  • kms_key_location: string - la región donde se encuentra tu clave maestra del sistema de gestión de claves

Si tu KMS reside en un proyecto de GCP distinto de aquel en el que registraste Workload Identity de OpenAI, asegúrate de que el proyecto que contiene Workload Identity de OpenAI tenga al menos KMS habilitado en 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"
}'

Respuesta de ejemplo

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

Solicitud de ejemplo

  • type: string - siempre  «azure»,

  • name: string - un nombre descriptivo para tu configuración

  • tenant_id: string - el UUID de tu tenant de Azure

  • vault_uri: string - el URI del almacén de Azure que contiene la clave maestra que gestionas

  • key_name: string - el nombre de la clave maestra de Azure Key Vault que gestionas.

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

Respuesta de ejemplo

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

Eliminar una clave externa registrada en tu organización

Nota: solo puedes eliminar una clave externa si no está asociada a ningún proyecto de API activo ni a ningún Área de trabajo. Si está asociada a un proyecto de API activo, archiva primero ese proyecto. Si está asociada a un Área de trabajo, la clave no se puede eliminar.

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Obtener las claves externas registradas en tu organización

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Validar una clave externa

Puedes usar este endpoint para comprobar varias cosas

  • Que tu configuración de nube externa sigue siendo válida con OpenAI después de hacer cambios (verás una respuesta correcta)

  • Que la revocación de tu clave se ha realizado correctamente, OpenAI la está procesando y surtirá efecto cuando caduquen las TTL de caché de 1 hora (verás una respuesta de error)

Solicitud de ejemplo

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

Respuesta de ejemplo

{
 "status": "success"
}

O bien, se muestra un error procedente del proveedor de nube.

Endpoints a nivel de proyecto

Crear un proyecto nuevo con un ID de clave externa

Es el mismo endpoint Create Project existente, con el parámetro external_key_id añadido en la solicitud y la respuesta.

Solicitud de ejemplo

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

Respuesta de ejemplo

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

[Restringido] Actualizar un proyecto existente con un ID de clave externa

Es el mismo endpoint Update Project existente, con el parámetro external_key_id añadido en la solicitud y la respuesta.


Recomendamos crear nuevos proyectos de API para tus cargas de trabajo de EKM. Si quieres usar EKM en todos tus proyectos de API existentes, pídeselo a tu director de cuenta y te añadiremos a la feature flag. Ten en cuenta las siguientes prácticas recomendadas antes de implantar EKM en tus proyectos de producción existentes.

  • Prueba primero todas las funciones de la API que uses en producción en tu proyecto de API de EKM de prueba

  • Haz una implantación gradual en lugar de aplicar EKM a todos los proyectos de API de producción a la vez

Solicitud de ejemplo

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

Listar todos los proyectos de tu organización

Es el mismo endpoint existente, pero con external_key_id añadido en la respuesta de la API

Solicitud de ejemplo

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

Respuesta de ejemplo

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

¿Te ha resultado útil este artículo?