Sažetak
Pristup
Krajnje točke za EKM dostupne su u API-ju za upravljanje putem administratorskog API ključa. https://platform.openai.com/settings/organization/admin-keys (nemojte upotrebljavati običan API ključ). Administratorski API ključevi dostupni su vlasnicima organizacije.
Upotrijebite
api.external_keys.writeza stvaranje ili brisanje vanjskih ključeva, aapi.external_keys.readza popisivanje, dohvaćanje ili provjeru valjanosti vanjskih ključeva. Jedan ključ treba oba opsega ovlasti samo ako mora obavljati i operacije čitanja i operacije pisanja.
Upotreba
Vaša konfiguracija EKM-a registrira se na razini organizacije putem nove krajnje točke https://api.openai.com/v1/organization/external_keys.
Registracijom konfiguracije EKM-a dobivate external_key_id u obliku extkey_xxxx.
Konfiguracije EKM-a aktiviraju se na razini projekta prosljeđivanjem vrijednosti external_key_id u tijelu zahtjeva postojećoj krajnjoj točki za izradu projekta https://api.openai.com/v1/organization/projects.
Ograničenja
Najprije morate testirati EKM na novom projektu putem API-ja za upravljanje.
Preporučujemo stvaranje novih projekata za radna opterećenja koja upotrebljavaju EKM. Prije uvođenja EKM-a u postojeće produkcijske projekte uzmite u obzir sljedeće preporučene prakse.
Najprije u testnom API projektu s EKM-om isprobajte sve značajke API-ja koje upotrebljavate u produkciji.
Uvodite EKM postupno, umjesto da ga odjednom omogućite u svim produkcijskim API projektima.
Endpointi na razini organizacije
Registrirajte vanjski ključ u svojoj organizaciji
AWS
Primjer zahtjeva:
type: niz znakova – uvijek „aws”
name: niz znakova – prepoznatljiv naziv vaše konfiguracije
role_arn: niz znakova – ARN uloge koju će OpenAI preuzeti u vašem oblaku
kms_arn: niz znakova – ARN glavnog ključa kojim upravljate u sustavu za upravljanje ključevima
external_id: niz znakova – vaš ID organizacije ili ID API projekta
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>"
}'Primjer odgovora:
{
"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
Primjer zahtjeva:
type: niz znakova – uvijek „gcp”,
name: niz znakova – prepoznatljiv naziv vaše konfiguracije
workload_identity_project_number: niz znakova – broj GCP projekta u kojem ste registrirali identitet radnog opterećenja za OpenAI
workload_identity_pool_id: niz znakova – skup koji sadrži pružatelja usluge Workload Identity kojeg ste registrirali za OpenAI
workload_identity_provider_id: niz znakova – pružatelj usluge Workload Identity kojeg ste registrirali za OpenAI
audience: niz znakova – ciljna publika koju OpenAI treba proslijediti u tokenu pri preuzimanju uloge putem vašeg GCP STS-a
kms_project_id: niz znakova – naziv GCP projekta u kojem se nalazi vaš KMS
kms_key_ring_name: niz znakova – skup ključeva u sustavu za upravljanje ključevima koji sadrži glavni ključ kojim upravljate
kms_key_name: niz znakova – naziv glavnog ključa u sustavu za upravljanje ključevima
kms_key_location: niz znakova – regija u kojoj se nalazi vaš glavni ključ u sustavu za upravljanje ključevima
Ako se vaš KMS nalazi u drugom GCP projektu od onoga u kojem ste registrirali Workload Identity za OpenAI, provjerite je li KMS barem omogućen u projektu koji sadrži Workload Identity za OpenAI tako da otvorite 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"
}'Primjer odgovora:
{
"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
Primjer zahtjeva:
type: niz znakova – uvijek „azure”,
name: niz znakova – prepoznatljiv naziv vaše konfiguracije
tenant_id: niz znakova – UUID vašeg klijenta u sustavu Azure
vault_uri: niz znakova – URI trezora u sustavu Azure koji sadrži glavni ključ kojim upravljate
key_name: niz znakova – naziv glavnog ključa u servisu Azure Key Vault kojim upravljate.
Mora biti u obliku <org-xxx>--<any_name>
pri čemu je org-xxx vaš ID organizacije na platformi OpenAI, koji možete pronaći 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"
}'Primjer odgovora:
{
"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"
}OCI
Postavite i omogućite ključ AES-256 te odobrite pristup tvrtki OpenAI. Ključ mora imati oznaku slobodnog oblika openai_organization_id postavljenu na ID vaše organizacije u sustavu OpenAI. Upute za postavljanje potražite u članku: Konfiguriranje servisa OCI Vault za upravljanje ključevima u poduzeću.
Primjer zahtjeva:
type: niz znakova – uvijek "oci"
purpose: niz znakova – "ekm"; zadana vrijednost ako se izostavi
name: niz znakova – lako prepoznatljiv naziv konfiguracije
region: niz znakova – regija OCI-ja u kojoj se nalaze vaš trezor i ključ
vault_ocid: niz znakova – puni OCID vašeg trezora
key_ocid: niz znakova – puni OCID vašeg ključa AES-256
Za EKM nemojte prosljeđivati key_version_ocid.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Primjer odgovora:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}API pri uspjehu vraća HTTP 200. Spremite vraćeni id i upotrijebite ga kao external_key_id pri stvaranju projekta. Postojeće operacije popisivanja, dohvaćanja, provjere valjanosti i brisanja primjenjuju se i na registracije za OCI.
Za oporavak PSP-a upotrijebite zasebnu registraciju ključa RSA-3072 s postavkom purpose: "psp_decryption" i točnom vrijednošću key_version_ocid. Postavite psp_decryption_key_id na ID te registracije u sustavu OpenAI. Tvrtki OpenAI potreban je samo pristup za čitanje metapodataka i javnih ključeva za taj RSA ključ. Potpune upute za postavljanje potražite u članku: Postavljanje asimetričnih ključeva — OCI Vault.
Izbrišite vanjski ključ registriran za vašu organizaciju
Napomena: Brisanje je blokirano dok aktivni projekt ili radni prostor upotrebljava registraciju. Za EKM najprije arhivirajte povezane API projekte; registracija za EKM povezana s radnim prostorom ostaje zaštićena. Za oporavak PSP-a prije brisanja registracije zamijenite ili uklonite vrijednost psp_decryption_key_id u svakom aktivnom projektu koji se na nju poziva. Brisanjem registracije u sustavu OpenAI ne briše se ključ u oblaku.
Primjer zahtjeva
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Primjer odgovora
{
"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>"
}Dohvatite vanjske ključeve registrirane za vašu organizaciju
Bez filtra prema namjeni popis obuhvaća registracije za EKM i za oporavak PSP-a. Upotrijebite ?purpose=ekm ili ?purpose=psp_decryption za filtriranje prema namjeni.
Primjer zahtjeva
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Primjer odgovora
{
"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"
}Provjerite valjanost vanjskog ključa
Provjerom valjanosti provjerite može li OpenAI i dalje pristupiti vašem ključu u oblaku.
Za EKM OpenAI provjerava može li ključem šifrirati i dešifrirati podatke. Pojedinosti o opozivu i predmemoriranju potražite u smjernicama za životni ciklus ključa.
Za oporavak PSP-a OpenAI dohvaća javni ključ registrirane verzije i uspoređuje ga s pohranjenom snimkom. Uspješna provjera valjanosti ne potvrđuje da vaš identitet za oporavak može dešifrirati podatke. Neuspješna provjera valjanosti ne uklanja niti zamjenjuje pohranjenu snimku javnog ključa.
Dohvaćanje registracije metodom GET vraća pohranjenu konfiguraciju i ne provjerava ponovno pristup vašem ključu u oblaku.
Primjer zahtjeva
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Primjer odgovora
{
"status": "success"
}Ili pogreška koju je vratio pružatelj usluga u oblaku.
Endpointi na razini projekta
Izrada novog projekta s ID-jem vanjskog ključa
Ova krajnja točka jednaka je postojećoj krajnjoj točki za izradu projekta, uz dodatak parametra external_key_id u zahtjevu i odgovoru.
Primjer zahtjeva
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"
}'Primjer odgovora
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Ažurirajte postojeći projekt ID-jem vanjskog ključa
Ovo je isto kao postojeća krajnja točka za ažuriranje projekta, uz dodatak parametra external_key_id u zahtjevu i odgovoru.
Preporučujemo stvaranje novih API projekata za radna opterećenja koja upotrebljavaju EKM. Prije uvođenja EKM-a u postojeće produkcijske projekte uzmite u obzir sljedeće preporučene prakse.
Najprije u testnom API projektu s EKM-om isprobajte sve značajke API-ja koje upotrebljavate u produkciji.
Uvodite EKM postupno, umjesto da ga odjednom omogućite u svim produkcijskim API projektima.
Primjer zahtjeva
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"
}'Popis svih projekata u vašoj organizaciji
Ova krajnja točka jednaka je postojećoj, uz dodatak polja external_key_id u odgovoru API-ja.
Primjer zahtjeva
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Primjer odgovora
{
"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
}