Podsumowanie

Dostęp

• Punkty końcowe EKM są dostępne w Management API za pomocą klucza Admin API. https://platform.openai.com/settings/organization/admin-keys (nie używaj zwykłego klucza API). Klucze Admin API są dostępne dla właścicieli organizacji.

• Użyj api.external_keys.write, aby tworzyć lub usuwać klucze zewnętrzne, oraz api.external_keys.read, aby wyświetlać lub weryfikować klucze zewnętrzne. Pojedynczy klucz potrzebuje obu zakresów tylko wtedy, gdy musi wykonywać zarówno operacje odczytu, jak i zapisu.

• Obecnie musimy włączyć flagę funkcji dla Twojej organizacji, aby udostępnić te punkty końcowe. Wiesz, że masz tę flagę funkcji, jeśli w odpowiedzi z istniejącego punktu końcowego List Projects zobaczysz **external_key_id **: https://api.openai.com/v1/organization/projects

Użycie

• Twoja konfiguracja EKM jest rejestrowana na poziomie organizacji za pomocą nowego punktu końcowego https://api.openai.com/v1/organization/external_keys

• Zarejestrowanie konfiguracji EKM zwraca external_key_id w postaci extkey_xxxx

• Konfiguracje EKM są aktywowane na poziomie projektu przez przekazanie external_key_id w treści żądania do istniejącego punktu końcowego Create Project https://api.openai.com/v1/organization/projects

Ograniczenia

• Najpierw musisz przetestować EKM w nowym projekcie za pomocą Management API.

• Zalecamy tworzenie nowych projektów dla obciążeń EKM. Jeśli jednak chcesz używać EKM w istniejącym projekcie, możemy dodać Cię do flagi funkcji. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zwróć uwagę na następujące sprawdzone praktyki.

  • Najpierw przetestuj w testowym projekcie EKM API wszystkie funkcje API, których używasz w środowisku produkcyjnym

  • Wdrażaj stopniowo zamiast włączać EKM we wszystkich produkcyjnych projektach API naraz

Punkty końcowe na poziomie organizacji

Zarejestruj klucz zewnętrzny w swojej organizacji

AWS

Przykładowe żądanie

• type: string - zawsze „aws”

• name: string - Przyjazna nazwa konfiguracji

• role_arn: string - Role ARN, którą OpenAI przyjmie w Twojej chmurze

• kms_arn: string - ARN systemu Key Management System dla zarządzanego przez Ciebie klucza głównego

• external_id: string - Identyfikator 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: string - zawsze "gcp",

• name: string - Przyjazna nazwa konfiguracji

• workload_identity_project_number: string - 12-cyfrowy numer projektu GCP, w którym zarejestrowano Workload Identity dla OpenAI

• workload_identity_pool_id: string - Pula zawierająca dostawcę Workload Identity zarejestrowanego dla OpenAI

• workload_identity_provider_id: string - Dostawca Workload Identity zarejestrowany dla OpenAI

• audience: string - Odbiorca, którego OpenAI powinno przekazać w tokenie, gdy przyjmujemy rolę przez Twój GCP STS

• kms_project_id: string - Nazwa projektu GCP, w którym znajduje się Twój KMS

• kms_key_ring_name: string - Pęk kluczy systemu Key Management System zawierający zarządzany przez Ciebie klucz główny

• kms_key_name: string - Nazwa klucza głównego systemu Key Management System

• kms_key_location: string - Region, w którym znajduje się klucz główny systemu Key Management System

Jeśli Twój KMS znajduje się w innym projekcie GCP niż ten, w którym zarejestrowano Workload Identity dla OpenAI, upewnij się, że w projekcie zawierającym Workload Identity dla OpenAI jest co najmniej włączony KMS, przechodząc do 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: string - zawsze "azure",

• name: string - Przyjazna nazwa konfiguracji

• tenant_id: string - UUID dzierżawy Azure

• vault_uri: string - URI magazynu Azure zawierającego zarządzany przez Ciebie klucz główny

• key_name: string - Nazwa klucza głównego Azure Key Vault, którym zarządzasz.

  • Musi mieć postać <org-xxx>--<any_name>

  • gdzie org-xxx to identyfikator Twojej organizacji OpenAI, który 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 swojej organizacji

Uwaga: Możesz usunąć klucz zewnętrzny tylko wtedy, gdy nie jest skojarzony z żadnymi aktywnymi projektami. Jeśli jest skojarzony z aktywnym projektem, musisz najpierw zarchiwizować ten projekt.

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

Zweryfikuj klucz zewnętrzny

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

• Czy konfiguracja Twojej zewnętrznej chmury pozostaje prawidłowa w OpenAI po wprowadzeniu zmian (zobaczysz odpowiedź o powodzeniu)

• Czy unieważnienie klucza zostało wykonane poprawnie, jest przetwarzane przez OpenAI i zacznie obowiązywać po wygaśnięciu 1-godzinnych TTL pamięci podręcznej (zobaczysz 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"
}

Lub błąd zgłoszony przez dostawcę chmury.

Punkty końcowe na poziomie projektu

Utwórz nowy projekt z identyfikatorem klucza zewnętrznego

To jest to samo co istniejący punkt końcowy Create Project, z dodanym parametrem external_key_id w żądaniu i odpowiedzi.

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

[Ograniczone] Zaktualizuj istniejący projekt identyfikatorem klucza zewnętrznego

To jest to samo co istniejący punkt końcowy Update Project, z dodanym parametrem external_key_id w żądaniu i odpowiedzi.

Zalecamy tworzenie nowych projektów API dla obciążeń EKM. Jeśli chcesz używać EKM we wszystkich istniejących projektach API, skontaktuj się ze swoim account directorem, a dodamy Cię do flagi funkcji. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zwróć uwagę na następujące sprawdzone praktyki.

• Najpierw przetestuj w testowym projekcie EKM API wszystkie funkcje API, których używasz w środowisku produkcyjnym

• Wdrażaj stopniowo zamiast włączać EKM 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 wszystkie projekty w swojej organizacji

To jest to samo co istniejący punkt końcowy, ale z dodatkiem external_key_id w odpowiedzi API

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
}