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

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

Upravljajte vanjskim ključevima za EKM putem Management API-ja

Ažurirano: 14 days ago

Sažetak

Pristup

  • EKM endpointi dostupni su u Management API-ju 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 popisivanje ili provjeru valjanosti vanjskih ključeva. Jednom ključu potrebna su oba opsega samo ako mora obavljati i operacije čitanja i operacije pisanja.

  • Trenutačno moramo omogućiti ove endpointe za vašu organizaciju feature flagom. Znat ćete da imate feature flag ako vidite da postojeći endpoint List Projects vraća external_key_id : https://api.openai.com/v1/organization/projects

Upotreba

Ograničenja

  • Najprije morate testirati EKM na novom projektu putem Management API-ja.

  • Preporučujemo da pokrenete nove projekte za svoja EKM radna opterećenja. Međutim, ako želite EKM na postojećem projektu, možemo vas dodati na feature flag. Prije uvođenja EKM-a u postojeće produkcijske projekte imajte na umu sljedeće najbolje prakse.

    • Najprije testirajte sve API značajke koje upotrebljavate u produkciji u svojem testnom EKM API projektu

    • Primijenite postupno uvođenje umjesto dodavanja EKM-a u sve produkcijske API projekte odjednom

Endpointi na razini organizacije

Registrirajte vanjski ključ u svojoj organizaciji

AWS

Primjer zahtjeva

  • type: string -  uvijek „aws”

  • name: string -  Prikladan naziv vaše konfiguracije

  • role_arn: string - ARN uloge koju će OpenAI preuzeti u vašem oblaku

  • kms_arn: string - ARN sustava za upravljanje ključevima za glavni ključ kojim upravljate

  • external_id: string - ID vaše organizacije ili 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: string - uvijek  „gcp”,

  • name: string - Prikladan naziv vaše konfiguracije

  • workload_identity_project_number: string - 12-znamenkasti broj GCP projekta u kojem ste registrirali OpenAI Workload Identity

  • workload_identity_pool_id: string - Skup koji sadrži pružatelja Workload Identity koji ste registrirali za OpenAI

  • workload_identity_provider_id: string - Pružatelj Workload Identity koji ste registrirali za OpenAI

  • audience: string - Publika koju OpenAI treba proslijediti u tokenu kada preuzimamo ulogu putem vašeg GCP STS-a

  • kms_project_id: string - Naziv GCP projekta u kojem se nalazi vaš KMS

  • kms_key_ring_name: string - Prsten ključeva sustava za upravljanje ključevima koji sadrži glavni ključ kojim upravljate

  • kms_key_name: string - Naziv glavnog ključa sustava za upravljanje ključevima

  • kms_key_location: string - Regija u kojoj se nalazi vaš glavni ključ sustava za upravljanje ključevima

Ako se vaš KMS nalazi u drugom GCP projektu od onoga u kojem ste registrirali OpenAI Workload Identity, provjerite je li u projektu koji sadrži OpenAI Workload Identity barem omogućen KMS tako da odete na 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: string - uvijek  „azure”,

  • name: string - Prikladan naziv vaše konfiguracije

  • tenant_id: string - UUID vašeg Azure zakupca

  • vault_uri: string - URI Azure trezora koji sadrži glavni ključ kojim upravljate

  • key_name: string - Naziv glavnog ključa 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"
}

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

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

Ovaj endpoint možete upotrijebiti za provjeru nekoliko stvari

  • Vaša vanjska konfiguracija oblaka ostaje valjana za OpenAI nakon izmjena (vidjet ćete odgovor o uspjehu)

  • Opoziv ključa pravilno je izveden, OpenAI ga obrađuje i stupit će na snagu nakon isteka jednosatnog TTL-a predmemorije (vidjet ć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

Izradite novi projekt s ID-om vanjskog ključa

To je isto kao postojeći endpoint Create Project, 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": "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,
}

[Ograničeno] Ažurirajte postojeći projekt ID-om vanjskog ključa

To je isto kao postojeći endpoint Update Project, uz dodatak parametra external_key_id u zahtjevu i odgovoru.


Preporučujemo da pokrenete nove API projekte za svoja EKM radna opterećenja. Ako želite EKM na svim postojećim API projektima, obratite se svom account direktoru i dodat ćemo vas na feature flag. Prije uvođenja EKM-a u postojeće produkcijske projekte imajte na umu sljedeće najbolje prakse.

  • Najprije testirajte sve API značajke koje upotrebljavate u produkciji u svojem testnom EKM API projektu

  • Primijenite postupno uvođenje umjesto dodavanja EKM-a u sve produkcijske API projekte odjednom

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 popis svih projekata u svojoj organizaciji

To je isto kao postojeći endpoint, ali uz dodatak external_key_id u API odgovoru

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?