Хураангуй
Хандалт
EKM endpoints-д Management API-ээр Admin API түлхүүр ашиглан хандах боломжтой. https://platform.openai.com/settings/organization/admin-keys (ердийн API түлхүүр бүү ашигла). Admin API түлхүүрүүдийг байгууллагын эзэмшигчид ашиглах боломжтой.
Гадаад түлхүүр үүсгэх эсвэл устгахад
api.external_keys.write, гадаад түлхүүрүүдийг жагсаах эсвэл баталгаажуулахадapi.external_keys.readашиглана уу. Нэг түлхүүрт унших, бичих үйлдлийг хоёуланг нь хийх шаардлагатай үед л хоёр scope хоёулаа хэрэгтэй.Одоогоор бид танай байгууллагыг эдгээр endpoints-д feature flag-аар идэвхжүүлэх шаардлагатай. Одоо байгаа List Projects endpoint-оос external_key_id буцаж ирж байвал feature flag идэвхжсэн гэсэн үг: https://api.openai.com/v1/organization/projects
Хэрэглээ
Таны EKM тохиргоог байгууллагын түвшинд шинэ endpoint https://api.openai.com/v1/organization/external_keys дээр бүртгэнэ
EKM тохиргоог бүртгэхэд extkey_xxxx хэлбэрийн external_key_id буцаана
EKM тохиргоог одоо байгаа Create Project https://api.openai.com/v1/organization/projects endpoint-ийн body-д external_key_id дамжуулснаар төсөл-ийн түвшинд идэвхжүүлнэ
Хязгаарлалтууд
Та эхлээд Management API-аар шинэ төсөл дээр EKM-ийг турших ёстой.
EKM workload-ууддаа шинэ төслүүд эхлүүлэхийг бид зөвлөж байна. Гэхдээ одоо байгаа төсөл дээр EKM ашиглахыг хүсвэл бид таныг feature flag-д нэмж болно. EKM-ийг одоо байгаа production төслүүддээ нэвтрүүлэхээсээ өмнө дараах шилдэг практикийг анхаарна уу.
Эхлээд production-д ашигладаг бүх API боломжоо тестийн EKM API төсөл дээрээ шалга
Бүх production API төслүүдэд EKM-ийг нэг дор нэмэхийн оронд шаталсан нэвтрүүлэлт хэрэглэ
Байгууллагын түвшний endpoints
Танай байгууллагад гадаад түлхүүр бүртгэх
AWS
Жишээ хүсэлт
type: string - үргэлж “aws”
name: string - Тохиргоонд өгөх ойлгомжтой нэр
role_arn: string - Таны үүлэн орчинд OpenAI assume хийх Role ARN
kms_arn: string - Таны удирддаг мастер түлхүүрийн Key Management System ARN
external_id: string - Танай байгууллагын ID эсвэл API төслийн ID
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>
}'Жишээ хариу
{
"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
Жишээ хүсэлт
type: string - үргэлж "gcp",
name: string - Тохиргоонд өгөх ойлгомжтой нэр
workload_identity_project_number: string - OpenAI-ийн workload identity-г бүртгэсэн GCP төслийн 12 оронтой дугаар
workload_identity_pool_id: string - OpenAI-д зориулж бүртгэсэн Workload Identity provider-ийг агуулсан pool
workload_identity_provider_id: string - OpenAI-д зориулж бүртгэсэн Workload Identity provider
audience: string - OpenAI таны GCP STS-ээр role assume хийх үед токенд дамжуулах audience
kms_project_id: string - Таны KMS байрлаж буй GCP төслийн нэр
kms_key_ring_name: string - Таны удирддаг мастер түлхүүрийг агуулсан Key Management System key ring
kms_key_name: string - Key Management System мастер түлхүүрийн нэр
kms_key_location: string - Таны Key Management System мастер түлхүүр байрлаж буй бүс
Хэрэв таны KMS OpenAI-ийн Workload Identity-г бүртгэсэн төслөөс өөр GCP төсөлд байрладаг бол OpenAI-ийн Workload Identity-г агуулсан төсөлд дор хаяж KMS идэвхжсэн эсэхийг 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"
}'Жишээ хариу
{
"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
Жишээ хүсэлт
type: string - үргэлж "azure",
name: string - Тохиргоонд өгөх ойлгомжтой нэр
tenant_id: string - Таны Azure tenant UUID
vault_uri: string - Таны удирддаг мастер түлхүүрийг агуулсан Azure vault-ийн URI
key_name: string - Таны удирддаг Azure Key Vault мастер түлхүүрийн нэр.
Энэ нь <org-xxx>--<any_name> хэлбэртэй байх ёстой
энд org-xxx нь https://platform.openai.com/settings/organization/general дээрээс олох боломжтой таны OpenAI байгууллагын ID юм
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"
}'Жишээ хариу
{
"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"
}Танай байгууллагад бүртгэлтэй гадаад түлхүүрийг устгах
Тэмдэглэл: Идэвхтэй API төсөл эсвэл ажлын талбартай холбоогүй тохиолдолд л гадаад түлхүүрийг устгах боломжтой. Хэрэв идэвхтэй API төсөлтэй холбоотой бол эхлээд тэр төслийг архивлаарай. Ажлын талбартай холбоотой бол түлхүүрийг устгах боломжгүй.
Жишээ хүсэлт
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Жишээ хариу
{
"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>"
}Танай байгууллагад бүртгэлтэй гадаад түлхүүрүүдийг авах
Жишээ хүсэлт
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Жишээ хариу
{
"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"
}Гадаад түлхүүрийг баталгаажуулах
Энэ endpoint-ийг дараах хэд хэдэн зүйлийг шалгахад ашиглаж болно
Таны гадаад үүлэн тохиргоо өөрчлөлт хийсний дараа OpenAI-тай хүчинтэй хэвээр байгаа эсэх (амжилттай хариу харагдана)
Түлхүүр хүчингүй болгох ажиллагаа зөв хийгдсэн, OpenAI боловсруулж байгаа бөгөөд 1 цагийн кэшийн TTL-үүд дууссаны дараа хүчин төгөлдөр болох эсэх (алдааны хариу харагдана)
Жишээ хүсэлт
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Жишээ хариу
{
"status": "success"
}Эсвэл үүлэн үйлчилгээ үзүүлэгчээс алдаа буцаж ирсэн.
Төслийн түвшний endpoints
Гадаад түлхүүрийн ID-тай шинэ төсөл үүсгэх
Энэ нь одоо байгаа Create Project endpoint-той адил боловч хүсэлт ба хариунд external_key_id параметр нэмэгдсэн.
Жишээ хүсэлт
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"
}'Жишээ хариу
{
"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,
}[Хязгаарлагдсан] Одоо байгаа төслийг гадаад түлхүүрийн ID-гаар шинэчлэх
Энэ нь одоо байгаа Update Project endpoint-той адил боловч хүсэлт ба хариунд external_key_id параметр нэмэгдсэн.
EKM workload-ууддаа шинэ API төслүүд эхлүүлэхийг бид зөвлөж байна. Хэрэв та одоо байгаа бүх API төслүүд дээрээ EKM ашиглахыг хүсвэл account director-тойгоо холбогдоно уу; бид таныг feature flag-д нэмнэ. EKM-ийг одоо байгаа production төслүүддээ нэвтрүүлэхээсээ өмнө дараах шилдэг практикийг анхаарна уу.
Эхлээд production-д ашигладаг бүх API боломжоо тестийн EKM API төсөл дээрээ шалга
Бүх production API төслүүдэд EKM-ийг нэг дор нэмэхийн оронд шаталсан нэвтрүүлэлт хэрэглэ
Жишээ хүсэлт
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"
}'Танай байгууллагын бүх төслийг жагсаах
Энэ нь одоо байгаа endpoint-той адил боловч API хариунд external_key_id нэмэгдсэн.
Жишээ хүсэлт
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Жишээ хариу
{
"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
}