Saznajte kako upravljati vanjskim ključevima za EKM pomoću API-ja za upravljanje.

Sažetak

Pristup

Krajnje tačke za EKM dostupne su u API-ju za upravljanje putem administratorskog API ključa. https://platform.openai.com/settings/organization/admin-keys (nemojte koristiti obični API ključ). Administratorski API ključevi dostupni su vlasnicima organizacije.
Koristite api.external_keys.write za kreiranje ili brisanje vanjskih ključeva, a api.external_keys.read za prikaz njihove liste ili provjeru valjanosti. Jednom ključu potrebna su oba opsega dozvola samo ako mora obavljati i operacije čitanja i operacije pisanja.
Trenutno vašoj organizaciji moramo posebno omogućiti pristup ovim krajnjim tačkama putem zastavice funkcije. Znat ćete da je zastavica funkcije uključena ako se external_key_id pojavljuje u odgovoru postojeće krajnje tačke za prikaz liste projekata: https://api.openai.com/v1/organization/projects.

Upotreba

Vaša EKM konfiguracija registrira se na nivou organizacije putem nove krajnje tačke https://api.openai.com/v1/organization/external_keys.
Registracijom EKM konfiguracije dobivate external_key_id u obliku extkey_xxxx.
EKM konfiguracije aktiviraju se na nivou projekta prosljeđivanjem vrijednosti external_key_id u tijelu zahtjeva postojećoj krajnjoj tački za kreiranje projekta https://api.openai.com/v1/organization/projects.

Ograničenja

Prvo morate testirati EKM na novom projektu putem API-ja za upravljanje.
Preporučujemo da za radna opterećenja koja koriste EKM kreirate nove projekte. Međutim, ako želite EKM na postojećem projektu, možemo vam uključiti zastavicu funkcije. Prije uvođenja EKM-a u postojeće produkcijske projekte, uzmite u obzir sljedeće preporučene prakse.
- Prvo u testnom API projektu s EKM-om testirajte sve funkcije API-ja koje koristite u produkciji.
- Uvodite EKM postepeno, umjesto da ga odjednom uključite na svim produkcijskim API projektima.

Endpointi na nivou organizacije

Registrujte eksterni 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 sistemu 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 kada preuzimamo ulogu 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 – privjesak ključeva u sistemu za upravljanje ključevima koji sadrži glavni ključ kojim upravljate
kms_key_name: niz znakova – naziv glavnog ključa u sistemu za upravljanje ključevima
kms_key_location: niz znakova – regija u kojoj se nalazi vaš glavni ključ sistema za upravljanje ključevima

Ako se vaš KMS nalazi u drugom GCP projektu od onog u kojem ste registrirali Workload Identity za OpenAI, provjerite da je KMS barem omogućen u projektu koji sadrži Workload Identity za OpenAI tako što ćete otvoriti 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 Azure zakupca
vault_uri: niz znakova – URI Azure trezora koji sadrži glavni ključ kojim upravljate
key_name: niz znakova – naziv glavnog ključa kojim upravljate u usluzi Azure Key Vault.
- Mora biti u obliku <org-xxx>--<any_name>
- gdje 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"
}

Izbrišite vanjski ključ registriran u vašoj organizaciji

Napomena: Vanjski ključ možete izbrisati samo ako nije povezan ni s jednim aktivnim API projektom ili radnim prostorom. Ako je povezan s aktivnim API projektom, prvo 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>"
}

Dohvatite vanjske ključeve registrirane 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"
}

Provjerite valjanost vanjskog ključa

Ovu krajnju tačku možete koristiti da provjerite nekoliko stvari:

Da je vaša konfiguracija vanjskog oblaka i dalje valjana za OpenAI nakon što ste unijeli izmjene (dobit ćete odgovor koji potvrđuje uspjeh).
Da je opoziv ključa ispravno izvršen, da ga OpenAI obrađuje i da će stupiti na snagu nakon isteka jednosatnih perioda važenja (TTL) predmemorije (dobit ćete odgovor s greškom).

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 je prijavljena greška od pružaoca usluge u oblaku.

Endpointi na nivou projekta

Kreirajte novi projekt s ID-em vanjskog ključa

Ova krajnja tačka ista je kao postojeća krajnja tačka za kreiranje projekta, ali 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žurirajte postojeći projekt dodavanjem ID-a vanjskog ključa

Ova krajnja tačka ista je kao postojeća krajnja tačka za ažuriranje projekta, ali uz dodatak parametra external_key_id u zahtjevu i odgovoru.

Preporučujemo da za radna opterećenja koja koriste EKM kreirate nove API projekte. Ako želite EKM na svim postojećim API projektima, obratite se svom voditelju korisničkog računa i uključit ćemo vam zastavicu funkcije. Prije uvođenja EKM-a u postojeće produkcijske projekte, uzmite u obzir sljedeće preporučene prakse.

Prvo u testnom API projektu s EKM-om testirajte sve funkcije API-ja koje koristite u produkciji.
Uvodite EKM postepeno, umjesto da ga odjednom uključ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"
}'

Prikažite listu svih projekata u vašoj organizaciji

Ova krajnja tačka ista je kao postojeća, ali 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 (eksterni ključevi) u Management API-ju

Sažetak

Pristup

Upotreba

Ograničenja

Endpointi na nivou organizacije

Registrujte eksterni ključ u svojoj organizaciji

AWS

GCP

Azure

Izbrišite vanjski ključ registriran u vašoj organizaciji

Primjer zahtjeva

Primjer odgovora

Dohvatite vanjske ključeve registrirane u vašoj organizaciji

Primjer zahtjeva

Primjer odgovora

Provjerite valjanost vanjskog ključa

Primjer zahtjeva

Primjer odgovora

Endpointi na nivou projekta

Kreirajte novi projekt s ID-em vanjskog ključa

Primjer zahtjeva

Primjer odgovora

[Ograničen pristup] Ažurirajte postojeći projekt dodavanjem ID-a vanjskog ključa

Primjer zahtjeva

Prikažite listu svih projekata u vašoj organizaciji

Primjer zahtjeva

Primjer odgovora

Da li je ovaj članak bio koristan?