Yhteenveto
Käyttöoikeudet
EKM-endpointit ovat käytettävissä Management APIssa Admin API Key -avaimella. https://platform.openai.com/settings/organization/admin-keys (älä käytä tavallista API-avainta). Admin API -avaimet ovat organisaation omistajien käytettävissä.
Käytä
api.external_keys.write-laajuutta ulkoisten avainten luomiseen tai poistamiseen jaapi.external_keys.read-laajuutta ulkoisten avainten listaamiseen tai vahvistamiseen. Yksi avain tarvitsee molemmat laajuudet vain, jos sen on tehtävä sekä luku- että kirjoitustoimintoja.Meidän on tällä hetkellä otettava nämä endpointit organisaatiossasi käyttöön feature flagilla. Tiedät feature flagin olevan käytössä, jos näet arvon external_key_id nykyisen List Projects -endpointin palautuksessa: https://api.openai.com/v1/organization/projects
Käyttö
EKM-konfiguraatiosi rekisteröidään organisaatiotasolla uuden endpointin kautta: https://api.openai.com/v1/organization/external_keys
EKM-konfiguraation rekisteröinti palauttaa external_key_id-arvon muodossa extkey_xxxx
EKM-konfiguraatiot aktivoidaan projektitasolla välittämällä external_key_id nykyisen Create Project -endpointin https://api.openai.com/v1/organization/projects rungossa
Rajoitukset
Sinun on ensin testattava EKM:ää uudessa projektissa Management APIn kautta.
Suosittelemme uusien projektien luomista EKM-työkuormia varten. 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 nykyisissä tuotantoprojekteissasi.
Testaa ensin kaikki tuotannossa käyttämäsi API-ominaisuudet EKM-testi-API-projektissasi
Ota EKM käyttöön vaiheittain sen sijaan, että lisäisit sen kaikkiin tuotannon API-projekteihin kerralla
Organisaatiotason endpointit
Rekisteröi ulkoinen avain organisaatioosi
AWS
Esimerkkipyyntö
type: string – aina ”aws”
name: string – konfiguraatiolle annettava selkeä nimi
role_arn: string – roolin ARN, jonka OpenAI ottaa käyttöön pilvessäsi
kms_arn: string – hallinnoimasi pääavaimen Key Management System -ARN
external_id: string – 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: string – aina ”gcp”,
name: string – konfiguraatiolle annettava selkeä nimi
workload_identity_project_number: string – sen GCP-projektin 12-numeroinen projektinumero, johon rekisteröit OpenAI:n Workload Identityn
workload_identity_pool_id: string – pooli, joka sisältää OpenAI:lle rekisteröimäsi Workload Identity -palveluntarjoajan
workload_identity_provider_id: string – OpenAI:lle rekisteröimäsi Workload Identity -palveluntarjoaja
audience: string – kohdeyleisö, joka OpenAI:n tulisi välittää tokenissa, kun otamme roolin käyttöön GCP STS:si kautta
kms_project_id: string – sen GCP-projektin nimi, jossa KMS:si sijaitsee
kms_key_ring_name: string – Key Management System -avainrengas, joka sisältää hallinnoimasi pääavaimen
kms_key_name: string – Key Management System -pääavaimen nimi
kms_key_location: string – 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: string – aina ”azure”,
name: string – konfiguraatiolle annettava selkeä nimi
tenant_id: string – Azure-tenanttisi UUID
vault_uri: string – sen Azure-holvin URI, joka sisältää hallinnoimasi pääavaimen
key_name: string – hallinnoimasi Azure Key Vault -pääavaimen nimi.
Sen on oltava muodossa <org-xxx>--<any_name>
jossa org-xxx on OpenAI-organisaatiosi tunnus, 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 aktiivisiin API-projekteihin tai työtilaan. Jos se on liitetty aktiiviseen API-projektiin, arkistoi projekti ensin. Jos se on liitetty työtilaan, avainta ei voi poistaa.
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>"
}Nouda 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"
}Vahvista ulkoinen avain
Tällä endpointilla voit tarkistaa useita asioita
Ulkoinen pilvikonfiguraatiosi pysyy kelvollisena OpenAIssa tekemiesi muutosten jälkeen (näet onnistumisvastauksen)
Avaimen kumoaminen on tehty oikein, OpenAI käsittelee sitä, ja se tulee voimaan, kun yhden tunnin välimuistin TTL-ajat ovat päättyneet (näet virhevastauksen)
Esimerkkipyyntö
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Esimerkkivastaus
{
"status": "success"
}Tai pilvipalveluntarjoajan palauttama virhe.
Projektitason endpointit
Luo uusi projekti ulkoisen avaimen tunnuksella
Tämä on sama kuin nykyinen Create Project -endpoint, mutta pyyntöön ja vastaukseen on lisätty external_key_id-parametri.
Esimerkkipyyntö
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"
}'Esimerkkivastaus
{
"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,
}[Rajoitettu] Päivitä olemassa oleva projekti ulkoisen avaimen tunnuksella
Tämä on sama kuin nykyinen Update Project -endpoint, mutta pyyntöön ja vastaukseen on lisätty external_key_id-parametri.
Suosittelemme uusien API-projektien luomista EKM-työkuormia varten. Jos haluat EKM:n kaikkiin nykyisiin API-projekteihisi, pyydä asiakkuusjohtajaasi, niin lisäämme sinut feature flagiin. Huomioi seuraavat parhaat käytännöt, ennen kuin otat EKM:n käyttöön nykyisissä tuotantoprojekteissasi.
Testaa ensin kaikki tuotannossa käyttämäsi API-ominaisuudet EKM-testi-API-projektissasi
Ota EKM käyttöön vaiheittain sen sijaan, että lisäisit sen 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 nykyinen 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": "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
}