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.write per creare o eliminare chiavi esterne e api.external_keys.read per elencare o convalidare chiavi esterne. Una singola chiave richiede entrambi gli ambiti solo se deve eseguire sia operazioni di lettura che di scrittura.
Per questi endpoint, attualmente dobbiamo abilitare la tua organizzazione tramite il toogle di funzionalità. Puoi capire che il toogle è attivo se vedi il campo external_key_id restituito dall'endpoint esistente List Projects: https://api.openai.com/v1/organization/projects.

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.
Ti consigliamo di creare nuovi progetti per i tuoi carichi di lavoro EKM. Tuttavia, se vuoi EKM in un progetto esistente, possiamo abilitare la feature flag per te. Ti invitiamo a prendere nota delle seguenti migliori pratiche prima di implementare EKM nei tuoi progetti di produzione esistenti.
- 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"
}

Elimina una chiave esterna registrata nella tua organizzazione

Nota: puoi eliminare una chiave esterna solo se non è associata ad alcun progetto API attivo o ad alcuna area di lavoro. Se è associata a un progetto API attivo, archivia prima quel progetto. Se la chiave è associata a un'area di lavoro, non può essere eliminata.

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

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

Puoi usare questo endpoint per verificare vari aspetti:

Dopo le modifiche, la configurazione cloud esterna rimane valida per OpenAI (vedrai una risposta di successo).
La revoca della tua chiave è stata eseguita correttamente, è in fase di elaborazione da parte di OpenAI e avrà effetto dopo la scadenza dei TTL della cache di un'ora (vedrai una risposta di errore).

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

[Limitato] Aggiorna un progetto esistente con un ID chiave esterna

Questo è uguale all'endpoint Update Project esistente con l'aggiunta del parametro external_key_id nella richiesta e nella risposta.

Ti consigliamo di creare nuovi progetti API per i tuoi carichi di lavoro EKM. Se desideri EKM su tutti i tuoi progetti API esistenti, chiedi al tuo Account Director e ti aggiungeremo alla feature flag. Ti invitiamo a prendere nota delle seguenti migliori pratiche prima di implementare EKM nei tuoi progetti di produzione esistenti.

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
}

EKM (Chiavi esterne) nell'API di gestione

Riepilogo

Accesso

Utilizzo

Restrizioni

Endpoint a livello di organizzazione

Registra una chiave esterna per la tua organizzazione

AWS

GCP

Azure

Elimina una chiave esterna registrata nella tua organizzazione

Richiesta di esempio

Risposta di esempio

Visualizza le chiavi esterne registrate per la tua organizzazione

Richiesta di esempio

Risposta di esempio

Convalida una chiave esterna

Richiesta di esempio

Risposta di esempio

Endpoint a livello di progetto

Crea un nuovo progetto con una chiave esterna ID

Richiesta di esempio

Risposta di esempio

[Limitato] Aggiorna un progetto esistente con un ID chiave esterna

Richiesta di esempio

Elenca tutti i progetti della tua organizzazione

Richiesta di esempio

Risposta di esempio

Questo articolo è stato utile?