Yhteenveto

Käyttöoikeus

• EKM- endpointit ovat käytettävissä Management API:ssa Admin API Key -avaimella. https://platform.openai.com/settings/organization/admin-keys (älä käytä tavallista API-avainta). Admin API -avaimet ovat organisaation omistajien saatavilla.

• Käytä api.external_keys.write -oikeutta ulkoisten avainten luomiseen tai poistamiseen ja api.external_keys.read -oikeutta ulkoisten avainten listaamiseen tai validointiin. Yksi avain tarvitsee molemmat scopet vain, jos sen on suoritettava sekä luku- että kirjoitustoimintoja.

• Meidän on tällä hetkellä otettava nämä endpointit organisaatiossasi käyttöön feature flagilla. Tiedät, että feature flag on käytössäsi, jos olemassa olevasta List Projects -endpointista palautuu **external_key_id **: https://api.openai.com/v1/organization/projects

Käyttö

• EKM-konfiguraatiosi rekisteröidään organisaatiotasolla uuden endpointin https://api.openai.com/v1/organization/external_keys kautta

• EKM-konfiguraation rekisteröinti palauttaa external_key_id:n muodossa extkey_xxxx

• EKM-konfiguraatiot aktivoidaan projektitasolla välittämällä external_key_id olemassa olevan Create Project -https://api.openai.com/v1/organization/projects-endpointin runkoon

Rajoitukset

• Sinun on ensin testattava EKM:ää uudessa projektissa Management API:n kautta.

• Suosittelemme käynnistämään uusia projekteja EKM-työkuormillesi. Jos kuitenkin haluat EKM:n olemassa olevaan projektiin, voimme lisätä sinut feature flagiin. Huomioi seuraavat parhaat käytännöt ennen kuin otat EKM:n käyttöön olemassa olevissa tuotantoprojekteissasi.

  • Testaa ensin testi-EKM-API-projektissasi kaikki API-ominaisuudet, joita käytät tuotannossa

  • Ota käyttöön asteittain sen sijaan, että lisäisit EKM:n kaikkiin tuotannon API-projekteihin kerralla

Organisaatiotason endpointit

Rekisteröi ulkoinen avain organisaatioosi

AWS

Esimerkkipyyntö

• type: merkkijono - aina “aws”

• name: merkkijono - konfiguraatiosi helppolukuinen nimi

• role_arn: merkkijono - Role ARN, jonka OpenAI ottaa käyttöön pilvessäsi

• kms_arn: merkkijono - hallinnoimasi pääavaimen Key Management System ARN

• external_id: merkkijono - organisaatiosi tunnus tai API-projektin tunnus

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

Esimerkkivastaus

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

Esimerkkipyyntö

• type: merkkijono - aina "gcp",

• name: merkkijono - konfiguraatiosi helppolukuinen nimi

• workload_identity_project_number: merkkijono - 12-numeroinen GCP-projektinumero, johon rekisteröit OpenAI:n workload identityn

• workload_identity_pool_id: merkkijono - pooli, joka sisältää OpenAI:lle rekisteröimäsi Workload Identity -providerin

• workload_identity_provider_id: merkkijono - Workload Identity -provider, jonka rekisteröit OpenAI:lle

• audience: merkkijono - audience, jonka OpenAI:n tulee välittää tokenissa, kun otamme roolin GCP STS:si kautta

• kms_project_id: merkkijono - sen GCP-projektin nimi, jossa KMS:si sijaitsee

• kms_key_ring_name: merkkijono - Key Management System -avainrengas, joka sisältää hallinnoimasi pääavaimen

• kms_key_name: merkkijono - Key Management System -pääavaimen nimi

• kms_key_location: merkkijono - alue, jossa Key Management System -pääavaimesi sijaitsee

Jos KMS:si sijaitsee eri GCP-projektissa kuin se, johon rekisteröit OpenAI:n Workload Identityn, varmista, että OpenAI:n Workload Identityn sisältävässä projektissa on vähintään KMS käytössä siirtymällä osoitteeseen 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"
}'

Esimerkkivastaus

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

Esimerkkipyyntö

• type: merkkijono - aina "azure",

• name: merkkijono - konfiguraatiosi helppolukuinen nimi

• tenant_id: merkkijono - Azure-vuokraajasi UUID

• vault_uri: merkkijono - hallinnoimasi pääavaimen sisältävän Azure vaultin URI

• key_name: merkkijono - hallinnoimasi Azure Key Vault -pääavaimen nimi.

  • Sen on oltava muodossa <org-xxx>--<any_name>

  • jossa org-xxx on OpenAI-organisaatiotunnuksesi, jonka löydät osoitteesta 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"
}'

Esimerkkivastaus

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

Poista organisaatioosi rekisteröity ulkoinen avain

Huomautus: Voit poistaa ulkoisen avaimen vain, jos sitä ei ole liitetty mihinkään aktiivisiin projekteihin. Jos se on liitetty aktiiviseen projektiin, sinun on ensin arkistoitava kyseinen projekti.

Esimerkkipyyntö

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Esimerkkivastaus

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

Hae organisaatioosi rekisteröidyt ulkoiset avaimet

Esimerkkipyyntö

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Esimerkkivastaus

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

Validoi ulkoinen avain

Voit käyttää tätä endpointia useiden asioiden tarkistamiseen

• Ulkoinen pilvikonfiguraatiosi on edelleen kelvollinen OpenAI:n kanssa tehtyjesi muutosten jälkeen (näet onnistuneen vastauksen)

• Avaimen peruutus on tehty oikein, OpenAI käsittelee sitä, ja se tulee voimaan, kun 1 tunnin välimuistin TTL:t ovat vanhentuneet (näet virhevastausen)

Esimerkkipyyntö

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Esimerkkivastaus

{
 "status": "success"
}

Tai pilvipalveluntarjoajalta tullut virhe.

Projektitason endpointit

Luo uusi projekti ulkoisen avaimen tunnuksella

Tämä on sama kuin olemassa oleva Create Project -endpoint, johon on lisätty external_key_id-parametri pyyntöön ja vastaukseen.

Esimerkkipyyntö

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
   "name": "Jokin projekti",
   "external_key_id": "extkey_xxxx"
}'

Esimerkkivastaus

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Jokin projekti",
  "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,
}

[Rajoitettu] Päivitä olemassa oleva projekti ulkoisen avaimen tunnuksella

Tämä on sama kuin olemassa oleva Update Project -endpoint, johon on lisätty external_key_id-parametri pyyntöön ja vastaukseen.

Suosittelemme käynnistämään uusia API-projekteja EKM-työkuormillesi. Jos haluat EKM:n kaikkiin olemassa oleviin API-projekteihisi, pyydä account directoriasi, niin lisäämme sinut feature flagiin. Huomioi seuraavat parhaat käytännöt ennen kuin otat EKM:n käyttöön olemassa olevissa tuotantoprojekteissasi.

• Testaa ensin testi-EKM-API-projektissasi kaikki API-ominaisuudet, joita käytät tuotannossa

• Ota käyttöön asteittain sen sijaan, että lisäisit EKM:n kaikkiin tuotannon API-projekteihin kerralla

Esimerkkipyyntö

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

Listaa kaikki organisaatiosi projektit

Tämä on sama kuin olemassa oleva endpoint, mutta API-vastaukseen on lisätty external_key_id

Esimerkkipyyntö

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Esimerkkivastaus

{
  "object": "list",
  "data": [
    {
      "object": "organization.project",
      "id": "proj_xxxx",
      "name": "Projektin nimi",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}