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

Aprende a gestionar claves externas para EKM con la API de gestión.

Actualización: 24 minutes ago

Resumen

Acceso

  • Puedes 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 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 enumerarlas o validarlas. Una misma clave solo necesita ambos ámbitos si debe realizar operaciones tanto de lectura como de escritura.

  • Actualmente, tenemos que habilitar estos puntos de acceso para tu organización mediante un indicador de función. Sabrás que el indicador de función está activado si el punto de acceso existente para enumerar proyectos 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 gestión.

  • Te recomendamos crear nuevos proyectos para tus cargas de trabajo con EKM. No obstante, si quieres EKM en un proyecto existente, podemos activar el indicador de función para ti. Ten en cuenta las siguientes prácticas recomendadas antes de implementar EKM en tus proyectos existentes en producción.

    • Prueba primero todas las funciones de la API que usas en producción en tu proyecto de pruebas de la API con EKM.

    • Implementa EKM de forma gradual en lugar de habilitarlo en todos los proyectos de la API en 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.

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

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 de la API ni a ninguna Área de trabajo. Si está asociada a un proyecto activo de la API, archiva primero ese proyecto. Si está asociada a un Área de trabajo, no se puede eliminar la clave.

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

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

Puedes usar este punto de acceso para comprobar varios aspectos:

  • Que la configuración de tu nube externa sigue siendo válida para OpenAI tras los cambios que has realizado (verás una respuesta de éxito).

  • Que has revocado correctamente tu clave, que OpenAI está procesando la revocación y que esta surtirá efecto cuando caduquen los TTL de caché de 1 hora (verás una respuesta de error).

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

[Restringido] 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 la API para tus cargas de trabajo con EKM. Si quieres EKM en todos tus proyectos existentes de la API, solicítalo a tu responsable de cuenta y activaremos el indicador de función para ti. Ten en cuenta las siguientes prácticas recomendadas antes de implementar EKM en tus proyectos existentes en producción.

  • Prueba primero todas las funciones de la API que usas en producción en tu proyecto de pruebas de la API con EKM.

  • Implementa EKM de forma gradual en lugar de habilitarlo en todos los proyectos de la API en 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
}

¿Te ha resultado útil este artículo?