Tóm tắt
Truy cập
Bạn có thể truy cập các điểm cuối EKM trong API quản lý bằng khóa API quản trị. https://platform.openai.com/settings/organization/admin-keys (không sử dụng khóa API thông thường). Chủ sở hữu tổ chức có thể sử dụng khóa API quản trị.
Sử dụng
api.external_keys.writeđể tạo hoặc xóa khóa bên ngoài, vàapi.external_keys.readđể liệt kê, truy xuất hoặc xác thực khóa bên ngoài. Một khóa chỉ cần cả hai phạm vi quyền nếu phải thực hiện cả thao tác đọc và ghi.
Cách sử dụng
Cấu hình EKM của bạn được đăng ký ở cấp tổ chức qua điểm cuối mới https://api.openai.com/v1/organization/external_keys.
Khi đăng ký cấu hình EKM, bạn sẽ nhận được external_key_id có dạng extkey_xxxx.
Cấu hình EKM được kích hoạt ở cấp dự án bằng cách truyền external_key_id trong phần thân yêu cầu gửi tới điểm cuối Tạo dự án hiện có https://api.openai.com/v1/organization/projects.
Các hạn chế
Trước tiên, bạn phải thử nghiệm EKM trên một dự án mới thông qua API quản lý.
Chúng tôi khuyên bạn nên tạo các dự án mới cho khối lượng công việc EKM. Hãy lưu ý những phương pháp hay nhất sau đây trước khi triển khai EKM cho các dự án hiện có đang vận hành thực tế.
Trước tiên, hãy kiểm thử mọi tính năng API đang dùng trong môi trường thực tế trên dự án API thử nghiệm EKM của bạn.
Triển khai từng bước thay vì áp dụng EKM cùng lúc cho mọi dự án API đang vận hành thực tế.
Các endpoint cấp tổ chức
Đăng ký khóa bên ngoài trong tổ chức của bạn
AWS
Yêu cầu mẫu:
type: chuỗi - luôn là “aws”
name: chuỗi - Tên dễ nhận biết cho cấu hình của bạn
role_arn: chuỗi - ARN của vai trò mà OpenAI sẽ đảm nhận trong môi trường đám mây của bạn
kms_arn: chuỗi - ARN trong hệ thống quản lý khóa của khóa chính do bạn quản lý
external_id: chuỗi - ID tổ chức hoặc ID dự án API của bạn
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>"
}'Phản hồi mẫu:
{
"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
Yêu cầu mẫu:
type: chuỗi - luôn là “gcp”,
name: chuỗi - Tên dễ nhận biết cho cấu hình của bạn
workload_identity_project_number: chuỗi - Số dự án GCP nơi bạn đã đăng ký danh tính khối lượng công việc của OpenAI
workload_identity_pool_id: chuỗi - Nhóm chứa nhà cung cấp Workload Identity mà bạn đã đăng ký cho OpenAI
workload_identity_provider_id: chuỗi - Nhà cung cấp Workload Identity mà bạn đã đăng ký cho OpenAI
audience: chuỗi - Đối tượng nhận mà OpenAI cần truyền trong mã thông báo khi chúng tôi đảm nhận một vai trò thông qua GCP STS của bạn
kms_project_id: chuỗi - Tên dự án GCP chứa KMS của bạn
kms_key_ring_name: chuỗi - Vòng khóa trong hệ thống quản lý khóa chứa khóa chính do bạn quản lý
kms_key_name: chuỗi - Tên khóa chính trong hệ thống quản lý khóa
kms_key_location: chuỗi - Khu vực chứa khóa chính trong hệ thống quản lý khóa của bạn
Nếu KMS của bạn nằm trong một dự án GCP khác với dự án nơi bạn đã đăng ký Workload Identity của OpenAI, hãy đảm bảo dự án chứa Workload Identity của OpenAI ít nhất đã bật KMS bằng cách truy cập 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"
}'Phản hồi mẫu:
{
"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
Yêu cầu mẫu:
type: chuỗi - luôn là “azure”,
name: chuỗi - Tên dễ nhận biết cho cấu hình của bạn
tenant_id: chuỗi - UUID của đối tượng thuê Azure của bạn
vault_uri: chuỗi - URI của kho Azure chứa khóa chính do bạn quản lý
key_name: chuỗi - Tên khóa chính trong Azure Key Vault do bạn quản lý.
Tên phải có dạng <org-xxx>--<any_name>
trong đó org-xxx là ID tổ chức OpenAI của bạn, có thể tìm thấy tại 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"
}'Phản hồi mẫu:
{
"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"
}OCI
Thiết lập một khóa AES-256 ở trạng thái bật và cấp quyền truy cập cho OpenAI. Khóa phải có thẻ dạng tự do openai_organization_id được đặt thành ID tổ chức OpenAI của bạn. Để biết các bước thiết lập, xem: Cấu hình OCI Vault cho tính năng Quản lý khóa doanh nghiệp.
Yêu cầu mẫu:
type: chuỗi - luôn là "oci"
purpose: chuỗi - "ekm"; đây là giá trị mặc định nếu bỏ qua tham số này
name: chuỗi - Tên dễ nhận biết cho cấu hình của bạn
region: chuỗi - Vùng OCI chứa kho khóa và khóa của bạn
vault_ocid: chuỗi - OCID đầy đủ của kho khóa
key_ocid: chuỗi - OCID đầy đủ của khóa AES-256
Không truyền key_version_ocid cho EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Phản hồi mẫu:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}API trả về HTTP 200 khi thành công. Lưu id được trả về và dùng giá trị đó làm external_key_id khi tạo dự án. Các thao tác liệt kê, truy xuất, xác thực và xóa hiện có cũng áp dụng cho các bản đăng ký OCI.
Để khôi phục PSP, hãy dùng một bản đăng ký RSA-3072 riêng với purpose: "psp_decryption" và key_version_ocid chính xác. Đặt psp_decryption_key_id thành ID của bản đăng ký đó trên OpenAI. OpenAI chỉ cần quyền đọc siêu dữ liệu và các khóa công khai của khóa RSA đó. Để biết quy trình thiết lập đầy đủ, xem: Thiết lập khóa bất đối xứng — OCI Vault.
Xóa khóa bên ngoài đã đăng ký với tổ chức của bạn
Lưu ý: Thao tác xóa bị chặn khi một dự án hoặc không gian làm việc đang hoạt động còn sử dụng bản đăng ký đó. Đối với EKM, trước tiên hãy lưu trữ các dự án API liên kết; bản đăng ký EKM liên kết với không gian làm việc vẫn được bảo vệ khỏi việc xóa. Đối với việc khôi phục PSP, hãy thay thế hoặc xóa giá trị psp_decryption_key_id trên mọi dự án đang hoạt động có tham chiếu đến bản đăng ký trước khi xóa bản đăng ký đó. Xóa bản đăng ký trên OpenAI không xóa khóa đám mây.
Yêu cầu mẫu
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Phản hồi mẫu
{
"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>"
}Lấy các khóa bên ngoài đã đăng ký với tổ chức của bạn
Nếu không lọc theo mục đích, danh sách sẽ bao gồm cả bản đăng ký EKM và bản đăng ký khôi phục PSP. Sử dụng ?purpose=ekm hoặc ?purpose=psp_decryption để lọc theo mục đích.
Yêu cầu mẫu
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Phản hồi mẫu
{
"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"
}Xác thực khóa bên ngoài
Sử dụng thao tác xác thực để kiểm tra xem OpenAI có còn truy cập được khóa đám mây của bạn hay không.
Đối với EKM, OpenAI kiểm tra khả năng mã hóa và giải mã bằng khóa đó. Để biết cách hoạt động của việc thu hồi và lưu vào bộ nhớ đệm, xem: hướng dẫn về vòng đời khóa.
Đối với việc khôi phục PSP, OpenAI truy xuất khóa công khai của phiên bản đã đăng ký và so sánh với bản chụp đã lưu. Xác thực thành công không có nghĩa là danh tính dùng để khôi phục của bạn có thể giải mã. Xác thực thất bại không xóa hoặc thay thế bản chụp khóa công khai đã lưu.
Truy xuất bản đăng ký bằng GET sẽ trả về cấu hình đã lưu và không kiểm tra lại quyền truy cập vào khóa đám mây của bạn.
Yêu cầu mẫu
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Phản hồi mẫu
{
"status": "success"
}Hoặc một lỗi được trả về từ nhà cung cấp đám mây.
Các endpoint cấp dự án
Tạo dự án mới bằng ID khóa bên ngoài
Điểm cuối này giống điểm cuối Tạo dự án hiện có, nhưng bổ sung tham số external_key_id vào yêu cầu và phản hồi.
Yêu cầu mẫu
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"
}'Phản hồi mẫu
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Cập nhật dự án hiện có bằng ID khóa bên ngoài
Điểm cuối này giống điểm cuối cập nhật dự án hiện có, nhưng bổ sung tham số external_key_id trong yêu cầu và phản hồi.
Chúng tôi khuyên bạn nên tạo các dự án API mới cho khối lượng công việc EKM. Hãy lưu ý những phương pháp hay nhất sau đây trước khi triển khai EKM cho các dự án hiện có đang vận hành thực tế.
Trước tiên, hãy kiểm thử mọi tính năng API đang dùng trong môi trường thực tế trên dự án API thử nghiệm EKM của bạn.
Triển khai từng bước thay vì áp dụng EKM cùng lúc cho mọi dự án API đang vận hành thực tế.
Yêu cầu mẫu
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"
}'Liệt kê tất cả dự án trong tổ chức của bạn
Điểm cuối này giống điểm cuối hiện có, nhưng bổ sung external_key_id vào phản hồi API.
Yêu cầu mẫu
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Phản hồi mẫu
{
"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
}