Resumen
Acceso
Puedes 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.writepara crear o eliminar claves externas, yapi.external_keys.readpara enumerar, obtener o validar claves externas. Una clave solo necesita ambos ámbitos si debe realizar tanto operaciones de lectura como de escritura.
Uso
Tu configuración de EKM se registra a nivel de organización mediante un nuevo punto de acceso https://api.openai.com/v1/organization/external_keys.
Al registrar tu configuración de EKM, se devuelve un external_key_id con el formato extkey_xxxx.
Las configuraciones de EKM se activan a nivel de proyecto al incluir un external_key_id en el cuerpo de la solicitud al punto de acceso existente para crear proyectos https://api.openai.com/v1/organization/projects.
Restricciones
Primero debes probar EKM en un proyecto nuevo mediante la API de administración.
Te recomendamos crear nuevos proyectos para tus cargas de trabajo de EKM. Ten en cuenta las siguientes prácticas recomendadas antes de implementar 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 prueba con EKM.
Implementa EKM de forma gradual, en lugar de hacerlo en 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
Ejemplo de solicitud:
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 correspondiente a la clave maestra que gestionas
external_id: string - el ID de la organización o de tu proyecto de la 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>"
}'Ejemplo de respuesta:
{
"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
Ejemplo de solicitud:
type: string - siempre «gcp»,
name: string - un nombre descriptivo para tu configuración
workload_identity_project_number: string - el número del proyecto de GCP en el que registraste la identidad de carga de trabajo de OpenAI
workload_identity_pool_id: string - el grupo que contiene el proveedor de identidades de carga de trabajo que registraste para OpenAI
workload_identity_provider_id: string - el proveedor de identidades de carga de trabajo que registraste para OpenAI
audience: string - la audiencia que OpenAI debe incluir en el token al asumir un rol a través de tu STS de GCP
kms_project_id: string - el nombre del proyecto de GCP donde se encuentra tu KMS
kms_key_ring_name: string - el conjunto 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 se encuentra en un proyecto de GCP distinto de aquel en el que registraste la identidad de carga de trabajo de OpenAI, asegúrate de que el proyecto que contiene la identidad de carga de trabajo de OpenAI tenga al menos KMS habilitado. Para ello, ve a 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"
}'Ejemplo de respuesta:
{
"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
Ejemplo de solicitud:
type: string - siempre «azure»,
name: string - un nombre descriptivo para tu configuración
tenant_id: string - el UUID de tu 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.
Debe tener el formato <org-xxx>--<any_name>
donde org-xxx es el ID de la organización de OpenAI, que puedes encontrar en https://platform.openai.com/settings/organization/general
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"
}'Ejemplo de respuesta:
{
"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"
}OCI
Configura una clave AES-256 habilitada y concede acceso a OpenAI. La clave debe tener una etiqueta de formato libre openai_organization_id cuyo valor sea el ID de la organización de OpenAI. Para conocer los pasos de configuración, consulta: configurar OCI Vault para la gestión de claves empresariales.
Ejemplo de solicitud:
type: cadena - siempre "oci"
purpose: cadena - "ekm"; valor predeterminado si se omite
name: cadena - un nombre descriptivo para tu configuración
region: cadena - la región de OCI que contiene tu almacén y tu clave
vault_ocid: cadena - el OCID completo de tu almacén
key_ocid: cadena - el OCID completo de tu clave AES-256
No pases key_version_ocid para EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Ejemplo de respuesta:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}La API devuelve HTTP 200 si la operación se realiza correctamente. Guarda el id devuelto y úsalo como external_key_id al crear un proyecto. Las operaciones existentes de enumeración, obtención, validación y eliminación también se aplican a los registros de OCI.
Para la recuperación de PSP, usa un registro RSA-3072 independiente con purpose: "psp_decryption" y un key_version_ocid exacto. Establece psp_decryption_key_id en el ID de ese registro en OpenAI. OpenAI solo necesita acceso de lectura a los metadatos y las claves públicas de esa clave RSA. Para conocer el proceso completo de configuración, consulta: configurar claves asimétricas — OCI Vault.
Eliminar una clave externa registrada en tu organización
Nota: la eliminación se bloquea mientras un proyecto o Área de trabajo activos usen el registro. Para EKM, archiva primero los proyectos de API asociados; un registro de EKM asociado a un Área de trabajo permanece protegido. Para la recuperación de PSP, sustituye o borra el valor de psp_decryption_key_id en todos los proyectos activos que hagan referencia al registro antes de eliminarlo. Eliminar un registro de OpenAI no elimina la clave en la nube.
Ejemplo de solicitud
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Ejemplo de respuesta
{
"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
Si no se filtra por finalidad, la lista incluye tanto los registros de EKM como los de recuperación de PSP. Usa ?purpose=ekm o ?purpose=psp_decryption para filtrar por finalidad.
Ejemplo de solicitud
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Ejemplo de respuesta
{
"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
Usa la validación para comprobar que OpenAI sigue teniendo acceso a tu clave en la nube.
Para EKM, OpenAI comprueba que puede cifrar y descifrar con la clave. Para conocer el funcionamiento de la revocación y el almacenamiento en caché, consulta: guía del ciclo de vida de las claves.
Para la recuperación de PSP, OpenAI obtiene la clave pública de la versión registrada y la compara con la instantánea almacenada. Una validación correcta no confirma que tu identidad de recuperación pueda descifrar. Una validación fallida no elimina ni sustituye la instantánea almacenada de la clave pública.
Al obtener un registro mediante GET, se devuelve la configuración almacenada sin volver a comprobar el acceso a tu clave en la nube.
Ejemplo de solicitud
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Ejemplo de respuesta
{
"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 igual que el punto de acceso existente para crear proyectos, pero añade el parámetro external_key_id a la solicitud y a la respuesta.
Ejemplo de solicitud
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"
}'Ejemplo de respuesta
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Actualizar un proyecto existente con un ID de clave externa
Es igual que el punto de acceso existente para actualizar proyectos, pero añade el parámetro external_key_id a la solicitud y a la respuesta.
Te recomendamos crear nuevos proyectos de API para tus cargas de trabajo de EKM. Ten en cuenta las siguientes prácticas recomendadas antes de implementar 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 prueba con EKM.
Implementa EKM de forma gradual, en lugar de hacerlo en todos los proyectos de API de producción a la vez.
Ejemplo de solicitud
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"
}'Enumerar todos los proyectos de tu organización
Es igual que el punto de acceso existente, pero añade external_key_id a la respuesta de la API.
Ejemplo de solicitud
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Ejemplo de respuesta
{
"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
}