Podsumowanie
Dostęp
Punkty końcowe EKM są dostępne w API zarządzania za pomocą klucza API administratora. https://platform.openai.com/settings/organization/admin-keys (nie używaj zwykłego klucza API). Klucze API administratora są dostępne dla właścicieli organizacji.
Użyj
api.external_keys.write, aby tworzyć lub usuwać klucze zewnętrzne, orazapi.external_keys.read, aby wyświetlać ich listę, pobierać je lub weryfikować. Pojedynczy klucz potrzebuje obu zakresów uprawnień tylko wtedy, gdy musi wykonywać zarówno operacje odczytu, jak i zapisu.
Korzystanie
Konfiguracja EKM jest rejestrowana na poziomie organizacji za pomocą nowego punktu końcowego https://api.openai.com/v1/organization/external_keys.
Rejestracja konfiguracji EKM zwraca external_key_id w formacie extkey_xxxx.
Konfiguracje EKM są aktywowane na poziomie projektu przez przekazanie external_key_id w treści żądania do istniejącego punktu końcowego tworzenia projektu https://api.openai.com/v1/organization/projects.
Ograniczenia
Najpierw musisz przetestować EKM w nowym projekcie za pomocą API zarządzania.
Zalecamy tworzenie nowych projektów na potrzeby zadań korzystających z EKM. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zapoznaj się z poniższymi dobrymi praktykami.
Najpierw przetestuj wszystkie funkcje API używane w środowisku produkcyjnym w testowym projekcie API z EKM.
Wdrażaj EKM stopniowo, zamiast włączać je we wszystkich produkcyjnych projektach API naraz.
Endpoints na poziomie organizacji
Zarejestruj klucz zewnętrzny w organizacji
AWS
Przykładowe żądanie:
type: ciąg znaków – zawsze „aws”
name: ciąg znaków – czytelna nazwa konfiguracji
role_arn: ciąg znaków – ARN roli, którą OpenAI będzie przyjmować w Twojej chmurze
kms_arn: ciąg znaków – ARN zarządzanego przez Ciebie klucza głównego w systemie zarządzania kluczami
external_id: ciąg znaków – ID Twojej organizacji lub projektu API
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>"
}'Przykładowa odpowiedź:
{
"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
Przykładowe żądanie:
type: ciąg znaków – zawsze „gcp”,
name: ciąg znaków – czytelna nazwa konfiguracji
workload_identity_project_number: ciąg znaków – numeryczny identyfikator projektu GCP, w którym zarejestrowano tożsamość obciążenia OpenAI
workload_identity_pool_id: ciąg znaków – pula zawierająca dostawcę Workload Identity zarejestrowanego dla OpenAI
workload_identity_provider_id: ciąg znaków – dostawca Workload Identity zarejestrowany dla OpenAI
audience: ciąg znaków – odbiorca, którego OpenAI ma wskazać w tokenie podczas przyjmowania roli za pośrednictwem Twojej usługi GCP STS
kms_project_id: ciąg znaków – nazwa projektu GCP, w którym znajduje się Twój KMS
kms_key_ring_name: ciąg znaków – pierścień kluczy w systemie zarządzania kluczami zawierający zarządzany przez Ciebie klucz główny
kms_key_name: ciąg znaków – nazwa klucza głównego w systemie zarządzania kluczami
kms_key_location: ciąg znaków – region, w którym znajduje się klucz główny Twojego systemu zarządzania kluczami
Jeśli Twój KMS znajduje się w innym projekcie GCP niż ten, w którym zarejestrowano Workload Identity OpenAI, upewnij się, że w projekcie z Workload Identity OpenAI jest przynajmniej włączony KMS. Możesz to sprawdzić pod adresem 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"
}'Przykładowa odpowiedź:
{
"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
Przykładowe żądanie:
type: ciąg znaków – zawsze „azure”,
name: ciąg znaków – czytelna nazwa konfiguracji
tenant_id: ciąg znaków – UUID Twojej dzierżawy Azure
vault_uri: ciąg znaków – URI magazynu Azure zawierającego zarządzany przez Ciebie klucz główny
key_name: ciąg znaków – nazwa zarządzanego przez Ciebie klucza głównego w Azure Key Vault.
Musi mieć format <org-xxx>--<any_name>
gdzie org-xxx to ID Twojej organizacji OpenAI, które znajdziesz pod adresem 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"
}'Przykładowa odpowiedź:
{
"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
Skonfiguruj aktywny klucz AES-256 i przyznaj OpenAI dostęp do niego. Klucz musi mieć tag swobodny openai_organization_id o wartości odpowiadającej ID organizacji w OpenAI. Instrukcje konfiguracji znajdziesz w artykule: Konfigurowanie OCI Vault na potrzeby zarządzania kluczami przedsiębiorstwa.
Przykładowe żądanie:
type: ciąg znaków — zawsze "oci"
purpose: ciąg znaków — "ekm"; wartość domyślna, gdy parametr zostanie pominięty
name: ciąg znaków — czytelna nazwa konfiguracji
region: ciąg znaków — region OCI, w którym znajdują się Twój magazyn kluczy i klucz
vault_ocid: ciąg znaków — pełny identyfikator OCID Twojego magazynu kluczy
key_ocid: ciąg znaków — pełny identyfikator OCID Twojego klucza AES-256
Nie przekazuj key_version_ocid w przypadku 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>"
}'Przykładowa odpowiedź:
{
"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 zwraca kod HTTP 200, gdy operacja się powiedzie. Zapisz zwróconą wartość id i użyj jej jako external_key_id podczas tworzenia projektu. Istniejące operacje wyświetlania listy, pobierania, weryfikacji i usuwania mają zastosowanie również do rejestracji OCI.
Na potrzeby odzyskiwania PSP użyj osobnej rejestracji RSA-3072 z purpose: "psp_decryption" i dokładną wartością key_version_ocid. Ustaw psp_decryption_key_id na identyfikator tej rejestracji w OpenAI. OpenAI potrzebuje jedynie dostępu do odczytu metadanych i kluczy publicznych tego klucza RSA. Pełne instrukcje konfiguracji znajdziesz w artykule: Konfigurowanie kluczy asymetrycznych — OCI Vault.
Usuń klucz zewnętrzny zarejestrowany w Twojej organizacji
Uwaga: Usuwanie jest zablokowane, dopóki z rejestracji korzysta aktywny projekt lub przestrzeń robocza. W przypadku EKM najpierw zarchiwizuj powiązane projekty API; rejestracja EKM powiązana z przestrzenią roboczą pozostaje chroniona przed usunięciem. W przypadku odzyskiwania PSP przed usunięciem rejestracji zastąp lub wyczyść psp_decryption_key_id w każdym aktywnym projekcie, który się do niej odwołuje. Usunięcie rejestracji w OpenAI nie usuwa klucza w chmurze.
Przykładowe żądanie
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Przykładowa odpowiedź
{
"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>"
}Pobierz klucze zewnętrzne zarejestrowane w Twojej organizacji
Bez filtra przeznaczenia lista obejmuje zarówno rejestracje EKM, jak i rejestracje na potrzeby odzyskiwania PSP. Użyj ?purpose=ekm lub ?purpose=psp_decryption, aby filtrować według przeznaczenia.
Przykładowe żądanie
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Przykładowa odpowiedź
{
"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"
}Zweryfikuj klucz zewnętrzny
Użyj weryfikacji, aby sprawdzić, czy OpenAI nadal ma dostęp do Twojego klucza w chmurze.
W przypadku EKM OpenAI sprawdza, czy może szyfrować i odszyfrowywać dane za pomocą klucza. Informacje o unieważnianiu kluczy i działaniu pamięci podręcznej znajdziesz we wskazówkach dotyczących cyklu życia klucza.
W przypadku odzyskiwania PSP OpenAI pobiera klucz publiczny zarejestrowanej wersji i porównuje go z zapisaną kopią. Pomyślna weryfikacja nie potwierdza, że tożsamość używana do odzyskiwania może odszyfrowywać dane. Nieudana weryfikacja nie usuwa ani nie zastępuje zapisanej kopii klucza publicznego.
Pobranie rejestracji metodą GET zwraca zapisaną konfigurację i nie sprawdza ponownie dostępu do Twojego klucza w chmurze.
Przykładowe żądanie
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Przykładowa odpowiedź
{
"status": "success"
}Albo błąd zgłoszony przez dostawcę chmury.
Endpoints na poziomie projektu
Utwórz nowy projekt z ID klucza zewnętrznego
Działa tak samo jak istniejący punkt końcowy tworzenia projektu, ale żądanie i odpowiedź zawierają dodatkowo parametr external_key_id.
Przykładowe żądanie
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"
}'Przykładowa odpowiedź
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Zaktualizuj istniejący projekt, podając identyfikator klucza zewnętrznego
To ten sam punkt końcowy co istniejący punkt końcowy aktualizacji projektu, ale z dodatkowym parametrem external_key_id w żądaniu i odpowiedzi.
Zalecamy tworzenie nowych projektów API na potrzeby zadań korzystających z EKM. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zapoznaj się z poniższymi dobrymi praktykami.
Najpierw przetestuj wszystkie funkcje API używane w środowisku produkcyjnym w testowym projekcie API z EKM.
Wdrażaj EKM stopniowo, zamiast włączać je we wszystkich produkcyjnych projektach API naraz.
Przykładowe żądanie
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"
}'Wyświetl listę wszystkich projektów w Twojej organizacji
Działa tak samo jak istniejący punkt końcowy, ale odpowiedź API zawiera dodatkowo pole external_key_id.
Przykładowe żądanie
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Przykładowa odpowiedź
{
"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
}