Povzetek
Dostop
Končne točke EKM so dostopne v API-ju za upravljanje s skrbniškim ključem API. https://platform.openai.com/settings/organization/admin-keys (ne uporabljajte običajnega ključa API). Skrbniški ključi API so na voljo lastnikom organizacij.
Za ustvarjanje ali brisanje zunanjih ključev uporabite
api.external_keys.write, za izpis seznama ali preverjanje veljavnosti zunanjih ključev paapi.external_keys.read. Posamezen ključ potrebuje oba obsega dovoljenj le, če mora izvajati tako operacije branja kot pisanja.Trenutno moramo vaši organizaciji dostop do teh končnih točk omogočiti z zastavico funkcije. Da je zastavica funkcije omogočena, lahko preverite tako, da v odzivu obstoječe končne točke za izpis seznama projektov vidite external_key_id: https://api.openai.com/v1/organization/projects.
Uporaba
Vaša konfiguracija EKM je registrirana na ravni organizacije prek nove končne točke https://api.openai.com/v1/organization/external_keys.
Ob registraciji konfiguracije EKM prejmete external_key_id v obliki extkey_xxxx.
Konfiguracije EKM aktivirate na ravni projekta tako, da v telesu zahteve obstoječi končni točki za ustvarjanje projektov https://api.openai.com/v1/organization/projects posredujete external_key_id.
Omejitve
EKM morate najprej preizkusiti v novem projektu prek API-ja za upravljanje.
Priporočamo, da za delovne obremenitve z EKM ustvarite nove projekte. Če pa želite EKM uporabljati v obstoječem projektu, vam lahko omogočimo zastavico funkcije. Pred uvedbo EKM v obstoječe produkcijske projekte upoštevajte naslednje dobre prakse.
Vse funkcije API-ja, ki jih uporabljate v produkciji, najprej preizkusite v testnem projektu API z EKM.
EKM uvajajte postopoma, namesto da ga omogočite v vseh produkcijskih projektih API hkrati.
Endpoints na ravni organizacije
Registrirajte zunanji ključ v svoji organizaciji
AWS
Primer zahteve:
type: niz – vedno »aws«
name: niz – opisno ime vaše konfiguracije
role_arn: niz – ARN vloge, ki jo bo OpenAI prevzel v vašem oblaku
kms_arn: niz – ARN glavnega ključa, ki ga upravljate v sistemu za upravljanje ključev
external_id: niz – ID vaše organizacije ali projekta 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>"
}'Primer odziva:
{
"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
Primer zahteve:
type: niz – vedno »gcp«,
name: niz – opisno ime vaše konfiguracije
workload_identity_project_number: niz – številka projekta GCP, v katerem ste registrirali identiteto delovne obremenitve za OpenAI
workload_identity_pool_id: niz – skupina, ki vsebuje ponudnika Workload Identity, registriranega za OpenAI
workload_identity_provider_id: niz – ponudnik Workload Identity, ki ste ga registrirali za OpenAI
audience: niz – ciljna publika, ki naj jo OpenAI posreduje v žetonu ob prevzemu vloge prek vaše storitve GCP STS
kms_project_id: niz – ime projekta GCP, v katerem je vaš KMS
kms_key_ring_name: niz – zbirka ključev v sistemu za upravljanje ključev, ki vsebuje glavni ključ, ki ga upravljate
kms_key_name: niz – ime glavnega ključa v sistemu za upravljanje ključev
kms_key_location: niz – regija, v kateri je glavni ključ vašega sistema za upravljanje ključev
Če je vaš KMS v drugem projektu GCP kot identiteta Workload Identity, ki ste jo registrirali za OpenAI, poskrbite, da ima projekt z identiteto Workload Identity za OpenAI vsaj omogočen KMS. To lahko uredite na 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"
}'Primer odziva:
{
"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
Primer zahteve:
type: niz – vedno »azure«,
name: niz – opisno ime vaše konfiguracije
tenant_id: niz – UUID vašega najemnika Azure
vault_uri: niz – URI trezorja Azure, ki vsebuje glavni ključ, ki ga upravljate
key_name: niz – ime glavnega ključa v storitvi Azure Key Vault, ki ga upravljate.
Biti mora v obliki <org-xxx>--<any_name>
kjer je org-xxx ID vaše organizacije OpenAI, ki ga najdete na 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"
}'Primer odziva:
{
"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"
}Izbrišite zunanji ključ, registriran v vaši organizaciji
Opomba: Zunanji ključ lahko izbrišete le, če ni povezan z nobenim aktivnim projektom API ali delovnim prostorom. Če je povezan z aktivnim projektom API, najprej arhivirajte ta projekt. Če je povezan z delovnim prostorom, ključa ni mogoče izbrisati.
Primer zahteve
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Primer odziva
{
"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>"
}Pridobite zunanje ključe, registrirane v vaši organizaciji
Primer zahteve
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Primer odziva
{
"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"
}Preverite veljavnost zunanjega ključa
S to končno točko lahko preverite več stvari:
Ali je vaša konfiguracija zunanjega oblaka po spremembah še vedno veljavna za OpenAI (prejeli boste odziv o uspehu).
Ali je bil preklic ključa pravilno izveden, ga OpenAI obdeluje in bo začel veljati po izteku enournega časa veljavnosti (TTL) predpomnilnikov (prejeli boste odziv z napako).
Primer zahteve
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Primer odziva
{
"status": "success"
}Ali pa napaka, ki jo vrne ponudnik oblaka.
Endpoints na ravni projekta
Ustvarite nov projekt z ID-jem zunanjega ključa
Ta končna točka je enaka obstoječi končni točki za ustvarjanje projektov, le da je v zahtevi in odzivu dodan parameter external_key_id.
Primer zahteve
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"
}'Primer odziva
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[Omejeno] Posodobite obstoječi projekt z ID-jem zunanjega ključa
Ta končna točka je enaka obstoječi končni točki za posodabljanje projektov, le da je v zahtevi in odzivu dodan parameter external_key_id.
Priporočamo, da za delovne obremenitve z EKM ustvarite nove projekte API. Če želite EKM uporabljati v vseh obstoječih projektih API, se obrnite na svojega skrbnika strank in omogočili vam bomo zastavico funkcije. Pred uvedbo EKM v obstoječe produkcijske projekte upoštevajte naslednje dobre prakse.
Vse funkcije API-ja, ki jih uporabljate v produkciji, najprej preizkusite v testnem projektu API z EKM.
EKM uvajajte postopoma, namesto da ga omogočite v vseh produkcijskih projektih API hkrati.
Primer zahteve
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"
}'Prikažite seznam vseh projektov v vaši organizaciji
Ta končna točka je enaka obstoječi, le da je v odzivu API-ja dodan external_key_id.
Primer zahteve
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Primer odziva
{
"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
}