Souhrn

Přístup

• Koncové body EKM jsou v rozhraní Management API přístupné prostřednictvím Admin API Key. https://platform.openai.com/settings/organization/admin-keys (nepoužívejte běžný klíč API). Admin API keys jsou k dispozici pro vlastníky organizace.

• Pomocí api.external_keys.write vytvářejte nebo odstraňujte externí klíče a pomocí api.external_keys.read vypisujte nebo ověřujte externí klíče. Jeden klíč potřebuje oba rozsahy jen tehdy, pokud musí provádět operace čtení i zápisu.

• V současnosti musíme pro vaši organizaci tyto koncové body povolit pomocí feature flagu. Že feature flag máte, poznáte tak, že ve stávajícím koncovém bodu List Projects uvidíte vracené pole **external_key_id **: https://api.openai.com/v1/organization/projects

Použití

• Vaše konfigurace EKM je na úrovni organizace registrována prostřednictvím nového koncového bodu https://api.openai.com/v1/organization/external_keys

• Registrace vaší konfigurace EKM vrátí external_key_id ve tvaru extkey_xxxx

• Konfigurace EKM se na úrovni projektu aktivují předáním external_key_id v těle stávajícího koncového bodu Create Project https://api.openai.com/v1/organization/projects

Omezení

• EKM musíte nejprve otestovat v novém projektu prostřednictvím Management API.

• Doporučujeme pro úlohy EKM vytvářet nové projekty. Pokud však chcete EKM v existujícím projektu, můžeme vás přidat do feature flagu. Než EKM nasadíte do svých stávajících produkčních projektů, vezměte prosím na vědomí následující osvědčené postupy.

  • Nejprve v testovacím EKM API projektu otestujte všechny funkce API, které používáte v produkci

  • Použijte postupné nasazení místo toho, abyste EKM najednou zavedli do všech produkčních API projektů

Koncové body na úrovni organizace

Registrace externího klíče ve vaší organizaci

AWS

Ukázkový požadavek

• type: string -  vždy „aws“

• name: string -  Uživatelsky přívětivý název vaší konfigurace

• role_arn: string - ARN role, kterou bude OpenAI přebírat ve vašem cloudovém prostředí

• kms_arn: string - ARN Key Management System pro hlavní klíč, který spravujete 

• external_id: string - ID vaší organizace nebo API projektu

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

Ukázková odpověď

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

Ukázkový požadavek

• type: string - vždy  „gcp“,

• name: string - Uživatelsky přívětivý název vaší konfigurace

• workload_identity_project_number: string - 12místné číslo projektu GCP, ve kterém jste zaregistrovali workload identity OpenAI

• workload_identity_pool_id: string - fond obsahující poskytovatele Workload Identity, kterého jste zaregistrovali pro OpenAI

• workload_identity_provider_id: string - poskytovatel Workload Identity, kterého jste zaregistrovali pro OpenAI

• audience: string - audience, kterou má OpenAI předat v tokenu, když převezmeme roli přes vaše GCP STS

• kms_project_id: string - název projektu GCP, ve kterém se nachází váš KMS

• kms_key_ring_name: string - key ring systému Key Management System obsahující hlavní klíč, který spravujete

• kms_key_name: string - název hlavního klíče systému Key Management System

• kms_key_location: string - oblast, ve které se nachází hlavní klíč vašeho systému Key Management System

Pokud se váš KMS nachází v jiném projektu GCP než ten, ve kterém jste zaregistrovali Workload Identity OpenAI, ujistěte se, že projekt obsahující Workload Identity OpenAI má alespoň povolený KMS, a to na adrese 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"
}'

Ukázková odpověď

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

Ukázkový požadavek

• type: string - vždy  „azure“,

• name: string - Uživatelsky přívětivý název vaší konfigurace

• tenant_id: string - UUID vašeho tenanta Azure

• vault_uri: string - URI trezoru Azure obsahujícího hlavní klíč, který spravujete 

• key_name: string - Název hlavního klíče Azure Key Vault, který spravujete. 

  • Musí mít tvar <org-xxx>--<any_name>

  • kde org-xxx je ID vaší organizace OpenAI, které najdete na adrese 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"
}'

Ukázková odpověď

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

Odstranění externího klíče zaregistrovaného ve vaší organizaci

Poznámka: Externí klíč můžete odstranit pouze tehdy, pokud není přidružen k žádným aktivním projektům. Pokud je přidružen k aktivnímu projektu, musíte tento projekt nejprve archivovat.

Ukázkový požadavek

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Ukázková odpověď

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

Získání externích klíčů zaregistrovaných ve vaší organizaci

Ukázkový požadavek

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Ukázková odpověď

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

Ověření externího klíče

Tento koncový bod můžete použít ke kontrole několika věcí

• Vaše externí cloudová konfigurace zůstává po provedených změnách pro OpenAI platná (uvidíte odpověď o úspěchu)

• Zneplatnění vašeho klíče je provedeno správně, OpenAI ho zpracovává a projeví se po vypršení 1hodinové cache TTL (uvidíte chybovou odpověď)

Ukázkový požadavek

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Ukázková odpověď

{
 "status": "success"
}

Nebo došlo k chybě od poskytovatele cloudu.

Koncové body na úrovni projektu

Vytvoření nového projektu s ID externího klíče

Jde o stejný koncový bod Create Project jako dosud, pouze s přidáním parametru external_key_id v požadavku a odpovědi.

Ukázkový požadavek

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

Ukázková odpověď

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

[Omezeno] Aktualizace existujícího projektu s ID externího klíče

Jde o stejný koncový bod Update Project jako dosud, pouze s přidáním parametru external_key_id v požadavku a odpovědi.

Doporučujeme pro úlohy EKM vytvářet nové API projekty. Pokud chcete EKM ve všech svých stávajících API projektech, obraťte se na svého account directora a my vás přidáme do feature flagu. Než EKM nasadíte do svých stávajících produkčních projektů, vezměte prosím na vědomí následující osvědčené postupy.

• Nejprve v testovacím EKM API projektu otestujte všechny funkce API, které používáte v produkci

• Použijte postupné nasazení místo toho, abyste EKM najednou zavedli do všech produkčních API projektů

Ukázkový požadavek

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

Výpis všech projektů ve vaší organizaci

Jde o stejný stávající koncový bod, ale s přidáním external_key_id do odpovědi API

Ukázkový požadavek

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Ukázková odpověď

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