Zistite, ako spravovať externé kľúče pre EKM pomocou rozhrania Management API.

Súhrn

Prístup

Koncové body EKM sú dostupné v rozhraní Management API prostredníctvom správcovského kľúča API. https://platform.openai.com/settings/organization/admin-keys (nepoužívajte bežný kľúč API). Správcovské kľúče API sú dostupné vlastníkom organizácie.
Na vytváranie alebo odstraňovanie externých kľúčov použite api.external_keys.write a na zobrazenie ich zoznamu alebo overenie použite api.external_keys.read. Jeden kľúč potrebuje oba rozsahy oprávnení iba vtedy, ak musí vykonávať operácie čítania aj zápisu.
Prístup k týmto koncovým bodom musíme vašej organizácii zatiaľ povoliť pomocou príznaku funkcie. Zapnutie príznaku funkcie spoznáte podľa toho, že existujúci koncový bod na výpis projektov vráti external_key_id: https://api.openai.com/v1/organization/projects.

Použitie

Vaša konfigurácia EKM sa registruje na úrovni organizácie prostredníctvom nového koncového bodu https://api.openai.com/v1/organization/external_keys.
Registráciou konfigurácie EKM získate external_key_id v tvare extkey_xxxx.
Konfigurácie EKM sa aktivujú na úrovni projektu odovzdaním external_key_id v tele požiadavky na existujúci koncový bod na vytvorenie projektu https://api.openai.com/v1/organization/projects.

Obmedzenia

EKM musíte najprv otestovať v novom projekte prostredníctvom rozhrania Management API.
Pre úlohy využívajúce EKM odporúčame vytvoriť nové projekty. Ak však chcete EKM v existujúcom projekte, môžeme vám zapnúť príznak funkcie. Pred nasadením EKM do existujúcich produkčných projektov sa oboznámte s nasledujúcimi osvedčenými postupmi.
- Všetky funkcie API, ktoré používate v produkcii, najprv otestujte v testovacom projekte API s EKM.
- EKM nasadzujte postupne, nie naraz do všetkých produkčných projektov API.

Endpoints na úrovni organizácie

Registrácia externého kľúča vo vašej organizácii

AWS

Príklad požiadavky:

type: reťazec – vždy „aws“
name: reťazec – zrozumiteľný názov vašej konfigurácie
role_arn: reťazec – ARN roly, ktorú OpenAI prevezme vo vašom cloude
kms_arn: reťazec – ARN hlavného kľúča, ktorý spravujete v systéme správy kľúčov
external_id: reťazec – ID vašej organizácie alebo projektu 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>"
}'

Príklad odpovede:

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

Príklad požiadavky:

type: reťazec – vždy „gcp“,
name: reťazec – zrozumiteľný názov vašej konfigurácie
workload_identity_project_number: reťazec – číselný identifikátor projektu GCP, v ktorom ste zaregistrovali identitu pracovnej záťaže OpenAI
workload_identity_pool_id: reťazec – fond obsahujúci poskytovateľa Workload Identity, ktorého ste zaregistrovali pre OpenAI
workload_identity_provider_id: reťazec – poskytovateľ Workload Identity, ktorého ste zaregistrovali pre OpenAI
audience: reťazec – cieľový príjemca, ktorého má OpenAI uviesť v tokene pri prevzatí roly prostredníctvom vašej služby GCP STS
kms_project_id: reťazec – názov projektu GCP, v ktorom sa nachádza váš KMS
kms_key_ring_name: reťazec – zväzok kľúčov v systéme správy kľúčov obsahujúci hlavný kľúč, ktorý spravujete
kms_key_name: reťazec – názov hlavného kľúča v systéme správy kľúčov
kms_key_location: reťazec – región, v ktorom sa nachádza váš hlavný kľúč v systéme správy kľúčov

Ak sa váš KMS nachádza v inom projekte GCP než v tom, v ktorom ste zaregistrovali Workload Identity pre OpenAI, overte na stránke https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview, že projekt obsahujúci Workload Identity pre OpenAI má aspoň povolený KMS.

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

Príklad odpovede:

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

Príklad požiadavky:

type: reťazec – vždy „azure“,
name: reťazec – zrozumiteľný názov vašej konfigurácie
tenant_id: reťazec – UUID vášho nájomníka Azure
vault_uri: reťazec – URI trezora Azure obsahujúceho hlavný kľúč, ktorý spravujete
key_name: reťazec – názov hlavného kľúča v službe Azure Key Vault, ktorý spravujete.
- Musí mať tvar <org-xxx>--<any_name>
- kde org-xxx je ID vašej organizácie OpenAI, ktoré nájdete na stránke 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"
}'

Príklad odpovede:

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

Odstránenie externého kľúča zaregistrovaného vo vašej organizácii

Poznámka: Externý kľúč môžete odstrániť iba vtedy, ak nie je priradený k žiadnemu aktívnemu projektu API ani pracovnému priestoru. Ak je priradený k aktívnemu projektu API, najprv tento projekt archivujte. Ak je kľúč priradený k pracovnému priestoru, nemožno ho odstrániť.

Príklad požiadavky

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

Príklad odpovede

{
  "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ískanie externých kľúčov zaregistrovaných vo vašej organizácii

Príklad požiadavky

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

Príklad odpovede

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

Overenie externého kľúča

Pomocou tohto koncového bodu môžete overiť niekoľko vecí:

Či je vaša konfigurácia externého cloudu aj po vykonaní zmien naďalej platná pre OpenAI (dostanete odpoveď o úspechu).
Či bol váš kľúč správne odvolaný, či OpenAI odvolanie spracúva a či nadobudne účinnosť po uplynutí hodinovej platnosti (TTL) záznamov vo vyrovnávacej pamäti (dostanete chybovú odpoveď).

Príklad požiadavky

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

Príklad odpovede

{
  "status": "success"
}

Alebo sa zobrazí chyba od poskytovateľa cloudu.

Endpoints na úrovni projektu

Vytvorenie nového projektu s ID externého kľúča

Ide o rovnaký koncový bod na vytvorenie projektu ako doteraz, no požiadavka aj odpoveď navyše obsahujú parameter external_key_id.

Príklad požiadavky

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

Príklad odpovede

{
  "object": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[Obmedzený prístup] Aktualizácia existujúceho projektu pomocou ID externého kľúča

Ide o rovnaký koncový bod na aktualizáciu projektu ako doteraz, no požiadavka aj odpoveď navyše obsahujú parameter external_key_id.

Pre úlohy využívajúce EKM odporúčame vytvoriť nové projekty API. Ak chcete EKM vo všetkých existujúcich projektoch API, obráťte sa na svojho obchodného zástupcu a zapneme vám príznak funkcie. Pred nasadením EKM do existujúcich produkčných projektov sa oboznámte s nasledujúcimi osvedčenými postupmi.

Všetky funkcie API, ktoré používate v produkcii, najprv otestujte v testovacom projekte API s EKM.
EKM nasadzujte postupne, nie naraz do všetkých produkčných projektov API.

Príklad požiadavky

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šetkých projektov vo vašej organizácii

Ide o rovnaký koncový bod ako doteraz, no odpoveď API navyše obsahuje external_key_id.

Príklad požiadavky

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

Príklad odpovede

{
  "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 (External Keys) v Management API

Súhrn

Prístup

Použitie

Obmedzenia

Endpoints na úrovni organizácie

Registrácia externého kľúča vo vašej organizácii

AWS

GCP

Azure

Odstránenie externého kľúča zaregistrovaného vo vašej organizácii

Príklad požiadavky

Príklad odpovede

Získanie externých kľúčov zaregistrovaných vo vašej organizácii

Príklad požiadavky

Príklad odpovede

Overenie externého kľúča

Príklad požiadavky

Príklad odpovede

Endpoints na úrovni projektu

Vytvorenie nového projektu s ID externého kľúča

Príklad požiadavky

Príklad odpovede

[Obmedzený prístup] Aktualizácia existujúceho projektu pomocou ID externého kľúča

Príklad požiadavky

Výpis všetkých projektov vo vašej organizácii

Príklad požiadavky

Príklad odpovede

Bol tento článok užitočný?