Sažetak

Pristup

• EKM krajnje točke dostupne su u Management API-ju putem Admin API ključa. https://platform.openai.com/settings/organization/admin-keys (nemojte koristiti običan API ključ). Admin 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 popis ili provjeru vanjskih ključeva. Jedan ključ treba oba scopea samo ako mora obavljati i operacije čitanja i pisanja.

• Trenutačno moramo omogućiti feature flag za vašu organizaciju za ove krajnje točke. Znate da imate feature flag ako vidite vraćen **external_key_id **iz postojećeg endpointa List Projects: https://api.openai.com/v1/organization/projects

Upotreba

• Vaša EKM konfiguracija registrira se na razini organizacije putem nove krajnje točke https://api.openai.com/v1/organization/external_keys

• Registracija vaše EKM konfiguracije vraća external_key_id u obliku extkey_xxxx

• EKM konfiguracije aktiviraju se na razini projekta prosljeđivanjem external_key_id u tijelu postojećeg endpointa Create Project https://api.openai.com/v1/organization/projects

Ograničenja

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

• Preporučujemo pokretanje novih projekata za vaša EKM radna opterećenja. Međutim, ako želite EKM na postojećem projektu, možemo vas dodati u feature flag. Imajte na umu sljedeće najbolje prakse prije nego što uvedete EKM u svoje postojeće produkcijske projekte.

  • Najprije testirajte sve API značajke koje koristite u produkciji u svom testnom EKM API projektu

  • Primijenite postupno uvođenje umjesto da odjednom popunite EKM na svim produkcijskim API projektima

Krajnje točke na razini organizacije

Registrirajte vanjski ključ u svojoj organizaciji

AWS

Primjer zahtjeva

• type: string - uvijek “aws”

• name: string - Prijateljski naziv za vašu konfiguraciju

• role_arn: string - Role ARN koji će OpenAI preuzeti u vašem oblaku

• kms_arn: string - ARN sustava Key Management System za glavni ključ kojim upravljate

• external_id: string - ID vaše 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: string - uvijek "gcp",

• name: string - Prijateljski naziv za vašu konfiguraciju

• workload_identity_project_number: string - 12-znamenkasti broj GCP projekta u kojem ste registrirali OpenAI-jev 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 - audience koji 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 - key ring sustava Key Management System koji sadrži glavni ključ kojim upravljate

• kms_key_name: string - naziv glavnog ključa sustava Key Management System

• kms_key_location: string - regija u kojoj se nalazi glavni ključ vašeg sustava Key Management System

Ako se vaš KMS nalazi u drugom GCP projektu od onog u kojem ste registrirali OpenAI-jev Workload Identity, provjerite je li u projektu koji sadrži OpenAI-jev 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 - Prijateljski naziv za vašu konfiguraciju

• tenant_id: string - UUID vašeg Azure tenanta

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

• key_name: string - Naziv glavnog ključa Azure Key Vaulta kojim upravljate.

  • Mora biti u obliku <org-xxx>--<any_name>

  • gdje je org-xxx ID vaše OpenAI organizacije 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 svojoj organizaciji

Napomena: Vanjski ključ možete izbrisati samo ako nije povezan ni s jednim aktivnim projektom. Ako je povezan s aktivnim projektom, najprije morate arhivirati taj projekt.

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 svojoj 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 točku možete upotrijebiti za provjeru nekoliko stvari

• Vaša vanjska konfiguracija oblaka ostaje valjana s OpenAI-jem nakon što ste unijeli promjene (vidjet ćete odgovor o uspjehu)

• Opoziv vašeg ključa pravilno je izvršen, OpenAI ga obrađuje i stupit će na snagu nakon isteka TTL predmemorije od 1 sata (vidjet ćete odgovor s pogreš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 došlo do pogreške od pružatelja usluge oblaka.

Krajnje točke na razini projekta

Stvorite novi projekt s ID-jem 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": "Neki projekt",
   "external_key_id": "extkey_xxxx"
}'

Primjer odgovora

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Neki projekt",
  "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 s ID-jem vanjskog ključa

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

Preporučujemo pokretanje novih API projekata za vaša EKM radna opterećenja. Ako želite EKM na svim svojim postojećim API projektima, obratite se direktoru zaduženom za vaš račun i dodat ćemo vas u feature flag. Imajte na umu sljedeće najbolje prakse prije nego što uvedete EKM u svoje postojeće produkcijske projekte.

• Najprije testirajte sve API značajke koje koristite u produkciji u svom testnom EKM API projektu

• Primijenite postupno uvođenje umjesto da odjednom popunite EKM 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"
}'

Navedite sve projekte u svojoj organizaciji

To je isto kao postojeća krajnja točka, 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": "Naziv projekta",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}