Shrnutí
Přístup
Koncové body EKM jsou dostupné v API pro správu prostřednictvím administrátorského klíče API. https://platform.openai.com/settings/organization/admin-keys (nepoužívejte běžný klíč API). Administrátorské klíče API jsou dostupné vlastníkům organizace.
K vytváření nebo mazání externích klíčů použijte
api.external_keys.writea k jejich výpisu nebo ověřeníapi.external_keys.read. Jeden klíč potřebuje oba rozsahy oprávnění pouze tehdy, pokud musí provádět operace čtení i zápisu.Přístup k těmto koncovým bodům musíme vaší organizaci v současnosti povolit pomocí příznaku funkce. Zapnutý příznak funkce poznáte podle toho, že stávající koncový bod pro výpis projektů vrací external_key_id: https://api.openai.com/v1/organization/projects.
Použití
Konfigurace EKM se registruje na úrovni organizace prostřednictvím nového koncového bodu https://api.openai.com/v1/organization/external_keys.
Při registraci konfigurace EKM se vrátí external_key_id ve tvaru extkey_xxxx.
Konfigurace EKM se aktivují na úrovni projektu předáním external_key_id v těle požadavku na stávající koncový bod pro vytvoření projektu https://api.openai.com/v1/organization/projects.
Omezení
EKM musíte nejprve otestovat v novém projektu prostřednictvím API pro správu.
Pro úlohy využívající EKM doporučujeme vytvořit nové projekty. Pokud však chcete EKM ve stávajícím projektu, můžeme vám zapnout příslušný příznak funkce. Než nasadíte EKM do stávajících produkčních projektů, zohledněte následující doporučené postupy.
Všechny funkce API, které používáte v produkčním prostředí, nejprve otestujte v testovacím projektu API s EKM.
EKM nasazujte postupně, nikoli do všech produkčních projektů API najednou.
Endpointy na úrovni organizace
Registrace externího klíče ve vaší organizaci
AWS
Ukázkový požadavek:
type: řetězec – vždy „aws“
name: řetězec – Srozumitelný název konfigurace
role_arn: řetězec – ARN role, kterou OpenAI převezme ve vašem cloudu
kms_arn: řetězec – ARN hlavního klíče, který spravujete v systému správy klíčů
external_id: řetězec – ID vaší organizace nebo 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>"
}'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: řetězec – vždy „gcp“,
name: řetězec – Srozumitelný název konfigurace
workload_identity_project_number: řetězec – Číslo projektu GCP, ve kterém jste zaregistrovali identitu úlohy OpenAI
workload_identity_pool_id: řetězec – Fond obsahující poskytovatele Workload Identity, kterého jste zaregistrovali pro OpenAI
workload_identity_provider_id: řetězec – Poskytovatel Workload Identity, kterého jste zaregistrovali pro OpenAI
audience: řetězec – Cílová skupina, kterou má OpenAI předat v tokenu při převzetí role prostřednictvím vaší služby GCP STS
kms_project_id: řetězec – Název projektu GCP, ve kterém se nachází vaše KMS
kms_key_ring_name: řetězec – Svazek klíčů v systému správy klíčů obsahující hlavní klíč, který spravujete
kms_key_name: řetězec – Název hlavního klíče v systému správy klíčů
kms_key_location: řetězec – Oblast, ve které se nachází váš hlavní klíč systému správy klíčů
Pokud se vaše KMS nachází v jiném projektu GCP než v tom, kde jste zaregistrovali Workload Identity pro OpenAI, ověřte na stránce https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview, že projekt obsahující Workload Identity pro OpenAI má alespoň povolenou službu 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"
}'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: řetězec – vždy „azure“,
name: řetězec – Srozumitelný název konfigurace
tenant_id: řetězec – UUID vašeho tenanta Azure
vault_uri: řetězec – URI trezoru Azure obsahujícího hlavní klíč, který spravujete
key_name: řetězec – Název hlavního klíče v Azure Key Vault, který spravujete.
Musí mít tvar <org-xxx>--<any_name>
kde org-xxx je ID vaší organizace OpenAI, které najdete na stránce 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"
}Smazání externího klíče registrovaného ve vaší organizaci
Poznámka: Externí klíč můžete smazat pouze tehdy, pokud není přidružen k žádnému aktivnímu projektu API ani pracovnímu prostoru. Pokud je přidružen k aktivnímu projektu API, nejprve tento projekt archivujte. Pokud je klíč přidružen k pracovnímu prostoru, nelze ho smazat.
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íčů registrovaný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
Pomocí tohoto koncového bodu můžete ověřit několik věcí:
Zda je konfigurace vašeho externího cloudu i po provedených změnách nadále platná pro OpenAI (obdržíte odpověď potvrzující úspěch).
Zda byl klíč správně odvolán, OpenAI odvolání zpracovává a projeví se po uplynutí hodinové doby platnosti (TTL) mezipamětí (obdrží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 se zobrazí chyba od poskytovatele cloudu.
Endpointy na úrovni projektu
Vytvoření nového projektu s ID externího klíče
Jde o stejný koncový bod pro vytvoření projektu jako dosud, ale požadavek a odpověď navíc obsahují parametr external_key_id.
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": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[Omezený přístup] Aktualizace stávajícího projektu s ID externího klíče
Jde o stejný koncový bod pro aktualizaci projektu jako dosud, ale požadavek a odpověď navíc obsahují parametr external_key_id.
Pro úlohy využívající EKM doporučujeme vytvořit nové projekty API. Pokud chcete EKM ve všech stávajících projektech API, obraťte se na svého obchodního zástupce a my vám zapneme příslušný příznak funkce. Než nasadíte EKM do stávajících produkčních projektů, zohledněte následující doporučené postupy.
Všechny funkce API, které používáte v produkčním prostředí, nejprve otestujte v testovacím projektu API s EKM.
EKM nasazujte postupně, nikoli do všech produkčních projektů API najednou.
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ý koncový bod jako dosud, ale odpověď API navíc obsahuje external_key_id.
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
}