OpenAI
Ova je stranica strojno prevedena. Pogledajte izvorni članak na engleskom jeziku.

EKM (vanjski ključevi) u Management API-ju

Saznajte kako upravljati vanjskim ključevima za EKM putem API-ja za upravljanje.

Ažurirano: 9 minutes ago

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.write za stvaranje ili brisanje vanjskih ključeva, a api.external_keys.read za 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

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.

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
}

Je li vam ovaj članak bio koristan?