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

EKM (claves externas) en la API de administración

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

Actualización: 4 days ago

Resumen

Acceso

  • Se puede acceder a los puntos de acceso de EKM 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 sola clave necesita ambos alcances solo si debe realizar operaciones de lectura y escritura.

  • Actualmente necesitamos activar una marca de función para tu organización en estos puntos de acceso. Sabrás que tienes la marca de función si ves **external_key_id **devuelto desde el punto de acceso actual List Projects: 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 proyectos nuevos para tus cargas de trabajo de EKM. Sin embargo, si quieres EKM en un proyecto existente, podemos añadirte a la marca de función. Ten en cuenta las siguientes prácticas recomendadas antes de implementar EKM en tus proyectos de producción existentes.

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

    • Aplica una implementación gradual en lugar de habilitar EKM en todos los proyectos de API de producción a la vez

Puntos de acceso de 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 - tu id de organización o id de 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": <tu id de organización o id de proyecto>
}'

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": <tu id de organización o id de proyecto>
}  

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 asumimos un rol a través de tu GCP STS

  • kms_project_id: string - el nombre del proyecto de GCP donde se encuentra 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 está en un proyecto de GCP distinto de aquel en el que registraste la Workload Identity de OpenAI, asegúrate de que el proyecto que contiene la Workload Identity de OpenAI tenga al menos KMS habilitado entrando 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": <tu id de organización o id de proyecto>,
   "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": <tu id de organización o id de proyecto>,
  "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 - tu UUID de inquilino 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 activo. Si está asociada a un proyecto activo, primero debes archivar ese proyecto.

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 punto de acceso para comprobar varias cosas

  • Que tu configuración de nube externa siga siendo válida con OpenAI después de haber realizado cambios (verás una respuesta de éxito)

  • Que la revocación de tu clave se haya hecho correctamente, OpenAI la esté procesando y surta efecto después de que hayan caducado 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, un error mostrado por el proveedor de nube.

Puntos de acceso de nivel de proyecto

Crear un proyecto nuevo con un ID de clave externa

Es igual que el punto de acceso actual Create Project, con la adición del parámetro external_key_id 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": "Algún proyecto",
   "external_key_id": "extkey_xxxx"
}'

Respuesta de ejemplo

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Algún proyecto",
  "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 igual que el punto de acceso actual Update Project, con la adición del parámetro external_key_id en la solicitud y la respuesta.

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

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

  • Aplica una implementación gradual en lugar de habilitar EKM en 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 igual que el punto de acceso actual, pero con la adición de external_key_id 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": "Nombre del proyecto",
      "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?