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

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 izradu ili brisanje vanjskih ključeva, a api.external_keys.read za njihov popis ili provjeru valjanosti. Jednom ključu potrebna su oba opsega ovlasti samo ako mora izvršavati operacije čitanja i pisanja.
Trenutačno vašoj organizaciji moramo omogućiti pristup tim krajnjim točkama putem zastavice značajke. Znat ćete da je zastavica značajke uključena ako postojeća krajnja točka za popis projekata u odgovoru vrati external_key_id: https://api.openai.com/v1/organization/projects.

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 izradu novih projekata za radna opterećenja koja upotrebljavaju EKM. Međutim, ako želite EKM na postojećem projektu, možemo vam uključiti zastavicu značajke. 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 testirajte sve značajke API-ja koje upotrebljavate u produkciji.
- Uvodite EKM postupno, umjesto da ga odjednom omogućite na 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"
}

Brisanje vanjskog ključa registriranog u vašoj organizaciji

Napomena: Vanjski ključ možete izbrisati samo ako nije povezan ni s jednim aktivnim API projektom ni radnim prostorom. Ako je povezan s aktivnim API projektom, najprije arhivirajte taj projekt. Ako je povezan s radnim prostorom, ključ se ne može izbrisati.

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>"
}

Dohvat vanjskih ključeva registriranih u vašoj organizaciji

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"
}

Provjera valjanosti vanjskog ključa

Ovom krajnjom točkom možete provjeriti sljedeće:

Je li vaša konfiguracija vanjskog oblaka i dalje valjana za OpenAI nakon unesenih promjena (dobit ćete odgovor o uspjehu).
Je li opoziv ključa pravilno izvršen, obrađuje li ga OpenAI i hoće li stupiti na snagu nakon isteka jednosatnog vremena valjanosti predmemorije (TTL) (dobit ćete odgovor o pogrešci).

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"
}

[Ograničen pristup] Ažuriranje postojećeg projekta ID-jem vanjskog ključa

Ova krajnja točka jednaka je postojećoj krajnjoj točki za ažuriranje projekta, uz dodatak parametra external_key_id u zahtjevu i odgovoru.

Preporučujemo izradu novih API projekata za radna opterećenja koja upotrebljavaju EKM. Ako želite EKM na svim postojećim API projektima, obratite se voditelju svojeg računa i uključit ćemo vam zastavicu značajke. 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 testirajte sve značajke API-ja koje upotrebljavate u produkciji.
Uvodite EKM postupno, umjesto da ga odjednom omogućite na 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
}

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

Sažetak

Pristup

Upotreba

Ograničenja

Endpointi na razini organizacije

Registrirajte vanjski ključ u svojoj organizaciji

AWS

GCP

Azure

Brisanje vanjskog ključa registriranog u vašoj organizaciji

Primjer zahtjeva

Primjer odgovora

Dohvat vanjskih ključeva registriranih u vašoj organizaciji

Primjer zahtjeva

Primjer odgovora

Provjera valjanosti vanjskog ključa

Primjer zahtjeva

Primjer odgovora

Endpointi na razini projekta

Izrada novog projekta s ID-jem vanjskog ključa

Primjer zahtjeva

Primjer odgovora

[Ograničen pristup] Ažuriranje postojećeg projekta ID-jem vanjskog ključa

Primjer zahtjeva

Popis svih projekata u vašoj organizaciji

Primjer zahtjeva

Primjer odgovora

Je li vam ovaj članak bio koristan?