OpenAI

EKM (Chiavi esterne) nell'API di gestione

Gestisci le chiavi esterne per EKM utilizzando l'API di gestione

Aggiornato: 13 days ago

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.

  • Attualmente dobbiamo abilitare la tua organizzazione a questi endpoint tramite feature flag. Sai di avere il feature flag se vedi **external_key_id **restituito dall'endpoint List Projects esistente: https://api.openai.com/v1/organization/projects

Utilizzo

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 API EKM di test tutte le funzionalità dell’API che usi in produzione

    • Applica un rollout graduale invece di popolare 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 - sempre “aws”

  • name: string - Un nome amichevole 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 - sempre "gcp",

  • name: string - Un nome descrittivo per la tua configurazione

  • workload_identity_project_number: string - Il numero di progetto GCP a 12 cifre dove 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 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 - sempre "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. 

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 attivo. Se è associata a un progetto attivo, devi prima archiviare quel progetto.

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

  • La configurazione cloud esterna rimane valida con OpenAI dopo aver apportato modifiche (vedrai una risposta di successo)

  • La revoca della 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 (riceverai 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": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[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 API EKM di test tutte le funzionalità dell’API che usi in produzione

  • Applica un rollout graduale invece di popolare 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
}

Questo articolo è stato utile?