Resum
Accés
Els punts finals d'EKM són accessibles a l'API de gestió mitjançant una clau d'API d'administració. https://platform.openai.com/settings/organization/admin-keys (no facis servir una clau d'API normal). Les claus d'API d'administració estan disponibles per als propietaris de l'organització.
Fes servir
api.external_keys.writeper crear o suprimir claus externes, iapi.external_keys.readper llistar, obtenir o validar claus externes. Una mateixa clau només necessita tots dos àmbits de permisos si ha de fer operacions tant de lectura com d'escriptura.
Ús
La teva configuració d'EKM es registra en l'àmbit de l'organització mitjançant un nou punt final: https://api.openai.com/v1/organization/external_keys.
En registrar la teva configuració d'EKM, es retorna un external_key_id amb el format extkey_xxxx.
Les configuracions d'EKM s'activen en l'àmbit del projecte passant un external_key_id al cos de la sol·licitud al punt final existent per crear projectes: https://api.openai.com/v1/organization/projects.
Restriccions
Primer has de provar EKM en un projecte nou mitjançant l'API de gestió.
Recomanem crear projectes nous per a les càrregues de treball d'EKM. Tingues en compte les bones pràctiques següents abans d'implementar EKM als teus projectes de producció existents.
Prova primer totes les funcions de l'API que fas servir en producció al teu projecte d'API de prova amb EKM.
Implementa EKM gradualment en lloc d'activar-lo a tots els projectes d'API de producció alhora.
endpoints de nivell d’organització
Registrar una clau externa a la vostra organització
AWS
Exemple de sol·licitud:
type: cadena - sempre "aws"
name: cadena - Un nom descriptiu per a la teva configuració
role_arn: cadena - L'ARN del rol que OpenAI assumirà al teu núvol
kms_arn: cadena - L'ARN del sistema de gestió de claus corresponent a la clau mestra que gestiones
external_id: cadena - El teu ID d'organització o de projecte d'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>"
}'Exemple de resposta:
{
"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
Exemple de sol·licitud:
type: cadena - sempre "gcp",
name: cadena - Un nom descriptiu per a la teva configuració
workload_identity_project_number: cadena - El número del projecte de GCP on has registrat la identitat de càrrega de treball d'OpenAI
workload_identity_pool_id: cadena - El grup que conté el proveïdor de Workload Identity que has registrat per a OpenAI
workload_identity_provider_id: cadena - El proveïdor de Workload Identity que has registrat per a OpenAI
audience: cadena - L'audiència que OpenAI ha de passar al testimoni quan assumim un rol mitjançant el teu STS de GCP
kms_project_id: cadena - El nom del projecte de GCP on es troba el teu KMS
kms_key_ring_name: cadena - L'anell de claus del sistema de gestió de claus que conté la clau mestra que gestiones
kms_key_name: cadena - El nom de la clau mestra del sistema de gestió de claus
kms_key_location: cadena - La regió on es troba la clau mestra del teu sistema de gestió de claus
Si el teu KMS es troba en un projecte de GCP diferent d'aquell on has registrat la identitat de Workload Identity d'OpenAI, assegura't que el projecte que conté aquesta identitat tingui, com a mínim, KMS habilitat. Pots comprovar-ho 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"
}'Exemple de resposta:
{
"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
Exemple de sol·licitud:
type: cadena - sempre "azure",
name: cadena - Un nom descriptiu per a la teva configuració
tenant_id: cadena - L'UUID del teu inquilí d'Azure
vault_uri: cadena - L'URI del magatzem d'Azure que conté la clau mestra que gestiones
key_name: cadena - El nom de la clau mestra d'Azure Key Vault que gestiones.
Ha de tenir el format <org-xxx>--<any_name>
on org-xxx és el teu ID d'organització d'OpenAI, que pots trobar a 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"
}'Exemple de resposta:
{
"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 clau AES-256 habilitada i concedeix-hi accés a OpenAI. La clau ha de tenir una etiqueta de format lliure openai_organization_id amb el teu ID d'organització d'OpenAI com a valor. Per veure els passos de configuració, consulta: Configuració d'OCI Vault per a la gestió de claus empresarials.
Exemple de sol·licitud:
type: cadena - sempre "oci"
purpose: cadena - "ekm"; el valor predeterminat si s'omet
name: cadena - Un nom descriptiu per a la configuració
region: cadena - La regió d'OCI que conté el magatzem de claus i la clau
vault_ocid: cadena - L'OCID complet del magatzem de claus
key_ocid: cadena - L'OCID complet de la clau AES-256
No passis key_version_ocid per a 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>"
}'Exemple de resposta:
{
"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>"
}L'API retorna HTTP 200 si l'operació es completa correctament. Desa el valor id retornat i fes-lo servir com a external_key_id en crear un projecte. Les operacions existents per llistar, obtenir, validar i suprimir també s'apliquen als registres d'OCI.
Per a la recuperació de PSP, fes servir un registre RSA-3072 independent amb purpose: "psp_decryption" i un valor exacte de key_version_ocid. Estableix psp_decryption_key_id amb el seu ID de registre d'OpenAI. OpenAI només necessita accés de lectura a les metadades i a les claus públiques d'aquesta clau RSA. Per veure la configuració completa, consulta: Configuració de claus asimètriques — OCI Vault.
Suprimeix una clau externa registrada a la teva organització
Nota: La supressió es bloqueja mentre un projecte o espai de treball actiu utilitzi el registre. Per a EKM, arxiva primer els projectes d'API associats; un registre d'EKM associat a un espai de treball continua protegit. Per a la recuperació de PSP, substitueix o esborra el valor de psp_decryption_key_id a tots els projectes actius que facin referència al registre abans de suprimir-lo. Suprimir un registre d'OpenAI no suprimeix la clau al núvol.
Exemple de sol·licitud
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Exemple de resposta
{
"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 les claus externes registrades a la teva organització
Sense un filtre de finalitat, la llista inclou tant els registres d'EKM com els de recuperació de PSP. Fes servir ?purpose=ekm o ?purpose=psp_decryption per filtrar per finalitat.
Exemple de sol·licitud
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Exemple de resposta
{
"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"
}Valida una clau externa
Fes servir la validació per comprovar que OpenAI encara pot accedir a la teva clau al núvol.
Per a EKM, OpenAI comprova que pot xifrar i desxifrar amb la clau. Per saber com funcionen la revocació i la memòria cau, consulta: guia del cicle de vida de les claus.
Per a la recuperació de PSP, OpenAI obté la clau pública de la versió registrada i la compara amb la instantània emmagatzemada. Una validació correcta no confirma que la teva identitat de recuperació pugui desxifrar. Una validació fallida no suprimeix ni substitueix la instantània emmagatzemada de la clau pública.
Obtenir un registre amb GET retorna la configuració emmagatzemada i no torna a comprovar l'accés a la teva clau al núvol.
Exemple de sol·licitud
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Exemple de resposta
{
"status": "success"
}O bé un error retornat pel proveïdor de núvol.
endpoints de nivell de projecte
Crea un projecte nou amb un ID de clau externa
És el mateix punt final que ja existeix per crear projectes, però amb el paràmetre external_key_id afegit a la sol·licitud i a la resposta.
Exemple de sol·licitud
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"
}'Exemple de resposta
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Actualitza un projecte existent amb un ID de clau externa
És el mateix punt final d'actualització de projectes existent, amb el paràmetre external_key_id afegit a la sol·licitud i a la resposta.
Recomanem crear projectes d'API nous per a les càrregues de treball d'EKM. Tingues en compte les bones pràctiques següents abans d'implementar EKM als teus projectes de producció existents.
Prova primer totes les funcions de l'API que fas servir en producció al teu projecte d'API de prova amb EKM.
Implementa EKM gradualment en lloc d'activar-lo a tots els projectes d'API de producció alhora.
Exemple de sol·licitud
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"
}'Llista tots els projectes de la teva organització
És el mateix punt final que ja existeix, però amb external_key_id afegit a la resposta de l'API.
Exemple de sol·licitud
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Exemple de resposta
{
"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
}