Riepilogo
Accesso
Gli endpoint EKM sono accessibili nell'API di gestione tramite una chiave API di amministrazione. https://platform.openai.com/settings/organization/admin-keys (non utilizzare una normale chiave API). Le chiavi API di amministrazione sono disponibili per i proprietari dell'organizzazione.
Usa
api.external_keys.writeper creare o eliminare chiavi esterne eapi.external_keys.readper elencare, recuperare o convalidare chiavi esterne. Una singola chiave richiede entrambi gli ambiti solo se deve eseguire operazioni sia di lettura sia di scrittura.
Utilizzo
La tua configurazione EKM è registrata a livello di organizzazione tramite un nuovo endpoint https://api.openai.com/v1/organization/external_keys.
La registrazione della configurazione EKM restituisce un external_key_id nel formato extkey_xxxx.
Le configurazioni EKM vengono attivate a livello di progetto passando un external_key_id nel corpo dell'endpoint esistente Create Project https://api.openai.com/v1/organization/projects .
Restrizioni
Devi prima testare EKM su un nuovo progetto tramite l'API di gestione.
Consigliamo di creare nuovi progetti per i carichi di lavoro EKM. Prima di implementare EKM nei tuoi progetti di produzione esistenti, tieni presenti le seguenti procedure consigliate.
Testa prima nel tuo progetto di prova dell'API EKM tutte le funzionalità dell'API che utilizzi in produzione.
Applica un'implementazione graduale, anziché inserire i dati EKM in tutti i progetti API di produzione contemporaneamente.
Endpoint a livello di organizzazione
Registra una chiave esterna per la tua organizzazione
AWS
Richiesta di esempio:
type: string - always “aws”
name: string - Un nome descrittivo per la tua configurazione
role_arn: string - L'ARN del ruolo che OpenAI assumerà nel tuo cloud
kms_arn: string - L'ARN del sistema di gestione delle chiavi per la chiave principale che gestisci
external_id: string - Il tuo ID organizzazione o ID progetto 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>"
}'Risposta di esempio:
{
"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
Richiesta di esempio:
type: string - always "gcp",
name: string - Un nome descrittivo per la tua configurazione
workload_identity_project_number: string - Il numero di progetto GCP in formato numerico in cui hai registrato l'identità del carico di lavoro di OpenAI
workload_identity_pool_id: string - Il pool contenente il provider di identità del carico di lavoro che hai registrato per OpenAI
workload_identity_provider_id: string - Il provider di identità del carico di lavoro che hai registrato per OpenAI
audience: string - Il pubblico che OpenAI deve includere nel token quando assumiamo un ruolo tramite il tuo GCP STS
kms_project_id: string - Il nome del progetto GCP in cui si trova il tuo KMS
kms_key_ring_name: string - Il keyring del sistema di gestione delle chiavi che contiene la chiave principale che gestisci
kms_key_name: string - Il nome della chiave principale del sistema di gestione delle chiavi
kms_key_location: string - L'area geografica in cui si trova la chiave principale del tuo sistema di gestione delle chiavi
Se il tuo KMS si trova in un progetto GCP diverso da quello in cui hai registrato l'identità del carico di lavoro di OpenAI, assicurati che il progetto contenente l'identità del carico di lavoro di OpenAI abbia almeno un KMS abilitato andando 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"
}'Risposta di esempio:
{
"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
Richiesta di esempio:
type: string - always "azure",
name: string - Un nome descrittivo per la tua configurazione
tenant_id: string - UUID del tenant di Azure
vault_uri: string - URI del vault di Azure contenente la chiave principale che gestisci
key_name: string - Il nome della chiave principale di Azure Key Vault che gestisci.
Deve avere il formato <org-xxx>--<any_name>
dove org-xxx è il tuo ID organizzazione OpenAI che puoi trovare su 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"
}'Risposta di esempio:
{
"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 chiave AES-256 abilitata e concedi a OpenAI l'accesso. La chiave deve avere un tag openai_organization_id in formato libero, il cui valore deve corrispondere all'ID della tua organizzazione OpenAI. Per i passaggi di configurazione, consulta: Configurazione di OCI Vault per la gestione delle chiavi aziendali.
Richiesta di esempio:
type: stringa - sempre "oci"
purpose: stringa - "ekm"; il valore predefinito se omesso
name: string - Un nome descrittivo per la tua configurazione
region: stringa - La regione OCI in cui si trovano il vault e la chiave
vault_ocid: stringa - L'OCID completo del tuo vault
key_ocid: stringa - L'OCID completo della tua chiave AES-256
Non specificare key_version_ocid per 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>"
}'Risposta di esempio:
{
"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 restituisce HTTP 200 in caso di successo. Salva l'id restituito e usalo come external_key_id quando crei un progetto. Le operazioni esistenti di elenco, recupero, convalida ed eliminazione si applicano anche alle registrazioni OCI.
Per il recupero tramite PSP, usa una registrazione RSA-3072 separata con purpose: "psp_decryption" e un valore key_version_ocid esatto. Imposta psp_decryption_key_id sull’ID di registrazione OpenAI corrispondente. Per questa chiave RSA, OpenAI necessita soltanto dell'accesso in lettura ai metadati e alle chiavi pubbliche. Per la configurazione completa, consulta: Configura le chiavi asimmetriche: OCI Vault.
Elimina una chiave esterna registrata nella tua organizzazione
Nota: l'eliminazione è bloccata finché un progetto o un'area di lavoro attiva utilizza la registrazione. Per EKM, archivia prima i progetti API associati; una registrazione EKM associata a un'area di lavoro rimane protetta. Per il ripristino PSP, sostituisci o rimuovi il valore di `psp_decryption_key_id` in ogni progetto attivo che fa riferimento alla registrazione prima di eliminarla. L'eliminazione di una registrazione OpenAI non comporta l'eliminazione della chiave nel cloud.
Richiesta di esempio
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Risposta di esempio
{
"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>"
}Visualizza le chiavi esterne registrate per la tua organizzazione
Senza un filtro per finalità, l'elenco include sia le registrazioni EKM sia quelle per il ripristino PSP. Usa ?purpose=ekm o ?purpose=psp_decryption per filtrare in base alla finalità.
Richiesta di esempio
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Risposta di esempio
{
"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"
}Convalida una chiave esterna
Utilizza la convalida per verificare che OpenAI possa ancora accedere alla tua chiave nel cloud.
Per EKM, OpenAI verifica di poter eseguire operazioni di crittografia e decrittografia con la chiave. Per informazioni sul comportamento relativo alla revoca e alla memorizzazione nella cache, consulta:guida completa al ciclo di vita delle chiavi.
Per il ripristino PSP, OpenAI recupera la chiave pubblica della versione registrata e la confronta con la copia memorizzata. Una convalida riuscita non conferma che la tua identità di ripristino sia autorizzata a eseguire operazioni di decrittografia. Una convalida non riuscita non elimina né sostituisce la copia della chiave pubblica memorizzata.
Il recupero di una registrazione tramite una richiesta GET restituisce la configurazione memorizzata e non verifica nuovamente l'accesso alla tua chiave nel cloud.
Richiesta di esempio
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Risposta di esempio
{
"status": "success"
}Oppure, si è verificato un errore dal provider cloud.
Endpoint a livello di progetto
Crea un nuovo progetto con una chiave esterna ID
Questo è uguale all'endpoint Create Project esistente, con l'aggiunta del parametro external_key_id nella richiesta e nella risposta.
Richiesta di esempio
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"
}'Risposta di esempio
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Aggiorna un progetto esistente con un ID di chiave esterna
Questo è uguale all'endpoint Update Project esistente con l'aggiunta del parametro external_key_id nella richiesta e nella risposta.
Consigliamo di creare nuovi progetti API per i carichi di lavoro EKM. Prima di implementare EKM nei tuoi progetti di produzione esistenti, tieni presenti le seguenti procedure consigliate.
Testa prima nel tuo progetto di prova dell'API EKM tutte le funzionalità dell'API che utilizzi in produzione.
Applica un'implementazione graduale, anziché inserire i dati EKM in tutti i progetti API di produzione contemporaneamente.
Richiesta di esempio
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"
}'Elenca tutti i progetti della tua organizzazione
Questo è lo stesso endpoint esistente ma con l'aggiunta di external_key_id nella risposta dell'API.
Richiesta di esempio
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Risposta di esempio
{
"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
}