Resumen

Acceso

Se puede acceder a los puntos de acceso de EKM en la API de gestión mediante una clave de API de administrador. https://platform.openai.com/settings/organization/admin-keys (no utilices una clave de API normal). Las claves de API de administración 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 habilitar tu organización mediante una marca de función para estos puntos de acceso. Sabrás que tienes la marca de función si ves que se devuelve **external_key_id** desde el punto de acceso existente de List Projects: https://api.openai.com/v1/organization/projects

Uso

Tu configuración de EKM está registrada a nivel de la organización mediante un nuevo punto de acceso https://api.openai.com/v1/organization/external_keys
Registrar tu configuración de EKM devuelve un external_key_id con el formato extkey_xxxx
Las configuraciones EKM se activan a nivel de proyecto pasando una external_key_id en el cuerpo del punto de acceso existente Create Project https://api.openai.com/v1/organization/projects

Restricciones

Primero debes probar EKM en un proyecto nuevo mediante la API de gestión.
Te recomendamos iniciar nuevos proyectos para las cargas de trabajo de EKM. Sin embargo, si quieres EKM en un proyecto existente, podemos agregarte a la bandera de características. Ten en cuenta las siguientes mejores prácticas antes de implementar EKM en proyectos de producción existentes.
- Primero, prueba en tu proyecto de API de EKM de prueba todas las funciones de la API que uses en producción
- Aplica un despliegue gradual en lugar de configurar EKM en todos los proyectos de API de producción de una sola vez

Puntos de acceso organizacionales

Registrar una clave externa en tu organización

AWS

Solicitud de ejemplo

type: cadena - siempre “aws”
name: cadena - Un nombre amigable para tu configuración
role_arn: cadena - El ARN del rol que OpenAI asumirá en tu nube
kms_arn: cadena - El ARN del sistema de administración de claves para la clave maestra que tú administras
external_id: cadena - ID de la organización o ID del proyecto de la API

curl -X POST \
-H "Content-tjson" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
  "type": "aws",
  "name": "AWS EKM Config",
  "role_arn": "arn:aws:iam:::role/<12_DIGIT_ACCOUNT_NUMBER><ROLE>",
  "kms_arn": "arn:aws:kms:::key/<REGION> <ACCOUNT_NUMBER><UUID>",
  "external_id": <tu id<your org id or project 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: cadena—siempre será "gcp",
name: cadena - Un nombre descriptivo para tu configuración
workload_identity_project_number: cadena - 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: cadena - El grupo que contiene el proveedor de identidad de carga de trabajo que registraste para OpenAI
workload_identity_provider_id: cadena - El proveedor de identidad de carga de trabajo que registraste para OpenAI
audience: cadena - La audiencia que OpenAI debe pasar en el token cuando asumimos un rol a través de tu STS de GCP
kms_project_id: cadena - El nombre del proyecto de GCP donde se encuentra tu KMS
kms_key_ring_name: cadena - El ARN del Sistema de administración de claves para la clave maestra que administra
kms_key_name: cadena - El nombre de la clave maestra del sistema de gestión de claves
kms_key_location: cadena - La región donde se encuentra la clave maestra de tu sistema de administració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 al menos tenga KMS habilitado; para ello, ve a https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview

curl -X POST \
-H "Content-tjson" \
-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": <el id de tu organización o el id de tu<your org id or project id> 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": <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: cadena - siempre «azure»,
name: cadena - Un nombre descriptivo para tu configuración
tenant_id: cadena - El UUID de tu tenant de Azure
vault_uri: cadena - El URI del almacén de Azure que contiene la clave maestra que tú administras
key_name: cadena - El nombre de la clave maestra de Azure Key Vault que tú administras.
- Debe tener la forma <org-xxx>--<any_name>
- donde org-xxx es el ID de tu organización de OpenAI que puedes encontrar en https://platform.openai.com/settings/organization/general

curl -X POST \
-H "Content-tjson" \
-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á asociado 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>"
}

Obtén las claves externas registradas en su 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 verificar varias cosas

Tu configuración de nube externa seguirá siendo válida con OpenAI después de que realices cambios (recibirás una confirmación exitosa)
La revocación de tu clave se realizó correctamente, OpenAI la está procesando y entrará en vigor después de que expire el 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, surgió un error del proveedor de servicios en la nube.

Puntos de acceso a nivel de proyecto

Crea un nuevo proyecto con un identificador de clave externa

Esto es igual al punto de acceso existente de 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": "Some Project",
   "extekey_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

Esto es lo mismo que el punto de acceso existente de Update Project, con la adición del parámetro external_key_id en la solicitud y la respuesta.

Te recomendamos crear nuevos proyectos de API para tus cargas de trabajo de EKM. Si quieres EKM en todos tus proyectos de API existentes, pídele a tu director de cuenta que te agregue al feature flag. Ten en cuenta las siguientes mejores prácticas antes de implementar EKM en proyectos de producción existentes.

Primero, prueba en tu proyecto de API de EKM de prueba todas las funciones de la API que uses en producción
Aplica un despliegue gradual en lugar de configurar EKM en todos los proyectos de API de producción de una sola 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"
}'

Enumera todos los proyectos de tu organización

Esto es igual al punto de acceso existente, 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.proj      "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
}

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

Resumen

Acceso

Uso

Restricciones

Puntos de acceso organizacionales

Registrar una clave externa en tu organización

AWS

Solicitud de ejemplo

Respuesta de ejemplo

GCP

Solicitud de ejemplo

Respuesta de ejemplo

Azure

Solicitud de ejemplo

Respuesta de ejemplo

Eliminar una clave externa registrada en tu organización

Solicitud de ejemplo

Respuesta de ejemplo

Obtén las claves externas registradas en su organización

Solicitud de ejemplo

Respuesta de ejemplo

Validar una clave externa

Solicitud de ejemplo

Respuesta de ejemplo

Puntos de acceso a nivel de proyecto

Crea un nuevo proyecto con un identificador de clave externa

Solicitud de ejemplo

Respuesta de ejemplo

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

Solicitud de ejemplo

Enumera todos los proyectos de tu organización

Solicitud de ejemplo

Respuesta de ejemplo

¿Este artículo te fue útil?