Dowiedz się, jak zarządzać kluczami zewnętrznymi EKM za pomocą API zarządzania.

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 zakresu api.external_keys.write, aby tworzyć lub usuwać klucze zewnętrzne, a zakresu api.external_keys.read, aby wyświetlać ich listę lub sprawdzać ich poprawność. Jeden klucz potrzebuje obu zakresów tylko wtedy, gdy ma służyć zarówno do odczytu, jak i zapisu.
Obecnie musimy włączyć flagę funkcji dla Twojej organizacji, aby udostępnić jej te punkty końcowe. Flaga funkcji jest włączona, jeśli pole external_key_id pojawia się w odpowiedzi istniejącego punktu końcowego wyświetlającego listę projektów: https://api.openai.com/v1/organization/projects.

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 do obsługi zadań korzystających z EKM. Jeśli jednak chcesz korzystać z EKM w istniejącym projekcie, możemy włączyć dla Ciebie flagę funkcji. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zapoznaj się z poniższymi zaleceniami.
- 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 jednocześnie.

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

Usuń klucz zewnętrzny zarejestrowany w Twojej organizacji

Uwaga: Klucz zewnętrzny można usunąć tylko wtedy, gdy nie jest powiązany z żadnym aktywnym projektem API ani przestrzenią roboczą. Jeśli jest powiązany z aktywnym projektem API, najpierw zarchiwizuj ten projekt. Jeśli jest powiązany z przestrzenią roboczą, nie można go usunąć.

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

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

Sprawdź poprawność klucza zewnętrznego

Za pomocą tego punktu końcowego możesz sprawdzić kilka rzeczy:

Czy po wprowadzeniu zmian konfiguracja Twojej zewnętrznej chmury nadal działa poprawnie z OpenAI (otrzymasz odpowiedź potwierdzającą powodzenie).
Czy unieważnienie klucza przebiegło prawidłowo, jest przetwarzane przez OpenAI i zacznie obowiązywać po upływie godzinnych okresów ważności (TTL) pamięci podręcznej (otrzymasz odpowiedź z błędem).

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

[Ograniczony dostęp] Zaktualizuj istniejący projekt, dodając ID klucza zewnętrznego

Działa tak samo jak istniejący punkt końcowy aktualizacji projektu, ale żądanie i odpowiedź zawierają dodatkowo parametr external_key_id.

Zalecamy tworzenie nowych projektów API do obsługi zadań korzystających z EKM. Jeśli chcesz korzystać z EKM we wszystkich istniejących projektach API, skontaktuj się ze swoim opiekunem klienta, a włączymy dla Ciebie flagę funkcji. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zapoznaj się z poniższymi zaleceniami.

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 jednocześnie.

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
}

EKM (klucze zewnętrzne) w Management API

Podsumowanie

Dostęp

Korzystanie

Ograniczenia

Endpoints na poziomie organizacji

Zarejestruj klucz zewnętrzny w organizacji

AWS

GCP

Azure

Usuń klucz zewnętrzny zarejestrowany w Twojej organizacji

Przykładowe żądanie

Przykładowa odpowiedź

Pobierz klucze zewnętrzne zarejestrowane w Twojej organizacji

Przykładowe żądanie

Przykładowa odpowiedź

Sprawdź poprawność klucza zewnętrznego

Przykładowe żądanie

Przykładowa odpowiedź

Endpoints na poziomie projektu

Utwórz nowy projekt z ID klucza zewnętrznego

Przykładowe żądanie

Przykładowa odpowiedź

[Ograniczony dostęp] Zaktualizuj istniejący projekt, dodając ID klucza zewnętrznego

Przykładowe żądanie

Wyświetl listę wszystkich projektów w Twojej organizacji

Przykładowe żądanie

Przykładowa odpowiedź

Czy ten artykuł był pomocny?