Povzetek
Dostop
EKM endpoints so dostopni v Management API prek Admin API Key. https://platform.openai.com/settings/organization/admin-keys (ne uporabljajte običajnega ključa API). Skrbniški ključi API so na voljo lastnikom organizacije.
Za ustvarjanje ali brisanje zunanjih ključev uporabite
api.external_keys.write, za prikaz seznama ali preverjanje zunanjih ključev paapi.external_keys.read. En ključ potrebuje oba obsega le, če mora izvajati tako bralne kot pisalne operacije.Trenutno moramo za vašo organizacijo omogočiti dostop do teh endpoints z zastavico funkcije. Da imate omogočeno zastavico funkcije, veste, če obstoječi endpoint List Projects vrne external_key_id : https://api.openai.com/v1/organization/projects
Uporaba
Vaša konfiguracija EKM je registrirana na ravni organizacije prek novega endpoint https://api.openai.com/v1/organization/external_keys
Registracija konfiguracije EKM vrne external_key_id v obliki extkey_xxxx
Konfiguracije EKM se aktivirajo na ravni projekta, tako da v telo obstoječega endpoint Create Project https://api.openai.com/v1/organization/projects posredujete external_key_id
Omejitve
EKM morate najprej preizkusiti v novem projektu prek API-ja Management API.
Priporočamo, da za svoje delovne obremenitve EKM zaženete nove projekte. Če pa želite EKM v obstoječem projektu, vas lahko dodamo v zastavico funkcije. Upoštevajte naslednje najboljše prakse, preden EKM uvedete v obstoječe produkcijske projekte.
Najprej v testnem projektu EKM API preskusite vse funkcije API, ki jih uporabljate v produkciji
Uporabite postopno uvedbo, namesto da EKM hkrati omogočite v vseh produkcijskih projektih API
Endpoints na ravni organizacije
Registrirajte zunanji ključ v svoji organizaciji
AWS
Primer zahteve
type: string - vedno »aws«
name: string - prijazno ime za vašo konfiguracijo
role_arn: string - ARN vloge, ki jo bo OpenAI prevzel v vašem oblaku
kms_arn: string - ARN sistema za upravljanje ključev za glavni ključ, ki ga upravljate
external_id: string - 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: string - vedno "gcp",
name: string - prijazno ime za vašo konfiguracijo
workload_identity_project_number: string - 12-mestna številka projekta GCP, kjer ste registrirali OpenAI-jevo identiteto delovne obremenitve
workload_identity_pool_id: string - skupina, ki vsebuje ponudnika Workload Identity, ki ste ga registrirali za OpenAI
workload_identity_provider_id: string - ponudnik Workload Identity, ki ste ga registrirali za OpenAI
audience: string - ciljna publika, ki naj jo OpenAI posreduje v žetonu, ko prek vašega GCP STS prevzamemo vlogo
kms_project_id: string - ime projekta GCP, kjer je vaš KMS
kms_key_ring_name: string - obroč ključev sistema za upravljanje ključev, ki vsebuje glavni ključ, ki ga upravljate
kms_key_name: string - ime glavnega ključa sistema za upravljanje ključev
kms_key_location: string - regija, kjer je glavni ključ vašega sistema za upravljanje ključev
Če je vaš KMS v drugem projektu GCP kot tisti, v katerem ste registrirali OpenAI-jevo Workload Identity, se prepričajte, da ima projekt z OpenAI-jevo Workload Identity omogočen vsaj KMS, tako da obiščete 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: string - vedno "azure",
name: string - prijazno ime za vašo konfiguracijo
tenant_id: string - UUID vašega najemnika Azure
vault_uri: string - URI trezorja Azure, ki vsebuje glavni ključ, ki ga upravljate
key_name: string - ime glavnega ključa Azure Key Vault, ki ga upravljate.
Imeti mora obliko <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 svoji 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 zunanji ključ
Ta endpoint lahko uporabite za preverjanje več stvari
Ali vaša zunanja konfiguracija oblaka po spremembah pri OpenAI ostaja veljavna (videli boste uspešen odziv)
Ali je preklic ključa pravilno izveden, ga OpenAI obdeluje in bo začel veljati po poteku 1-urnih predpomnilniških TTL-jev (videli 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
To je enako kot obstoječi endpoint Create Project, le da je v zahtevo in odziv 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": "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,
}[Omejeno] Posodobite obstoječi projekt z ID-jem zunanjega ključa
To je enako kot obstoječi endpoint Update Project, le da je v zahtevo in odziv dodan parameter external_key_id.
Priporočamo, da za svoje delovne obremenitve EKM zaženete nove projekte API. Če želite EKM v vseh obstoječih projektih API, se obrnite na svojega vodjo računa in dodali vas bomo v zastavico funkcije. Upoštevajte naslednje najboljše prakse, preden EKM uvedete v obstoječe produkcijske projekte.
Najprej v testnem projektu EKM API preskusite vse funkcije API, ki jih uporabljate v produkciji
Uporabite postopno uvedbo, namesto da EKM hkrati omogočite v vseh produkcijskih projektih API
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 svoji organizaciji
To je enako kot obstoječi endpoint, le da je v odziv API 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
}