Sammanfattning

Åtkomst

EKM-slutpunkter är tillgängliga i Management API via en API-nyckel för administratörer. https://platform.openai.com/settings/organization/admin-keys (använd inte en vanlig API-nyckel). API-nycklar för administratörer är tillgängliga för organisationsägare.
Använd api.external_keys.write för att skapa eller ta bort externa nycklar och api.external_keys.read för att lista eller validera externa nycklar. En enskild nyckel behöver båda behörigheterna endast om den ska utföra både läs- och skrivåtgärder.
För närvarande behöver vi aktivera en funktionsflagga för att ge din organisation åtkomst till dessa slutpunkter. Du vet att funktionsflaggan är aktiverad om external_key_id returneras från den befintliga slutpunkten för att lista projekt: https://api.openai.com/v1/organization/projects.

Användning

Din EKM-konfiguration registreras på organisationsnivå via en ny slutpunkt: https://api.openai.com/v1/organization/external_keys.
När du registrerar din EKM-konfiguration returneras ett external_key_id i formatet extkey_xxxx.
EKM-konfigurationer aktiveras på projektnivå genom att du skickar med ett external_key_id i begärans kropp till den befintliga slutpunkten för att skapa projekt: https://api.openai.com/v1/organization/projects.

Begränsningar

Du måste först testa EKM i ett nytt projekt via Management API.
Vi rekommenderar att du skapar nya projekt för dina EKM-arbetsbelastningar. Om du ändå vill använda EKM i ett befintligt projekt kan vi aktivera funktionsflaggan för dig. Följ dessa rekommendationer innan du inför EKM i dina befintliga produktionsprojekt.
- Testa först alla API-funktioner som du använder i produktion i ditt API-testprojekt med EKM.
- Inför EKM stegvis i stället för att aktivera det i alla API-projekt i produktion samtidigt.

Endpoints på organisationsnivå

Registrera en extern nyckel för din organisation

AWS

Exempel på begäran:

type: sträng – alltid ”aws”
name: sträng – Ett lättläst namn på din konfiguration
role_arn: sträng – ARN för den roll som OpenAI ska anta i din molnmiljö
kms_arn: sträng – ARN i nyckelhanteringssystemet för den huvudnyckel du hanterar
external_id: sträng – Ditt organisations-ID eller API-projekt-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>"
}'

Exempel på svar:

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

Exempel på begäran:

type: sträng – alltid ”gcp”,
name: sträng – Ett lättläst namn på din konfiguration
workload_identity_project_number: sträng – Det numeriska projektnumret för GCP-projektet där du registrerade OpenAI:s arbetsbelastningsidentitet
workload_identity_pool_id: sträng – Poolen som innehåller den Workload Identity-provider som du registrerade för OpenAI
workload_identity_provider_id: sträng – Den Workload Identity-provider som du registrerade för OpenAI
audience: sträng – Den målgrupp som OpenAI ska ange i token när vi antar en roll via din GCP STS
kms_project_id: sträng – Namnet på GCP-projektet där ditt KMS finns
kms_key_ring_name: sträng – Nyckelringen i nyckelhanteringssystemet som innehåller den huvudnyckel du hanterar
kms_key_name: sträng – Namnet på huvudnyckeln i nyckelhanteringssystemet
kms_key_location: sträng – Regionen där huvudnyckeln i ditt nyckelhanteringssystem finns

Om ditt KMS finns i ett annat GCP-projekt än det där du registrerade OpenAI:s Workload Identity ska du säkerställa att KMS åtminstone är aktiverat i projektet som innehåller OpenAI:s Workload Identity. Det gör du genom att gå till 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"
}'

Exempel på svar:

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

Exempel på begäran:

type: sträng – alltid ”azure”,
name: sträng – Ett lättläst namn på din konfiguration
tenant_id: sträng – UUID för din Azure-klientorganisation
vault_uri: sträng – URI för det Azure-valv som innehåller den huvudnyckel du hanterar
key_name: sträng – Namnet på den huvudnyckel i Azure Key Vault som du hanterar.
- Det måste ha formatet <org-xxx>--<any_name>
- där org-xxx är ditt organisations-ID hos OpenAI, som du hittar på 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"
}'

Exempel på svar:

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

Ta bort en extern nyckel som är registrerad i din organisation

Obs! Du kan bara ta bort en extern nyckel om den inte är kopplad till något aktivt API-projekt eller någon arbetsyta. Om den är kopplad till ett aktivt API-projekt måste du först arkivera projektet. Om den är kopplad till en arbetsyta går det inte att ta bort nyckeln.

Exempel på begäran

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Exempel på svar

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

Hämta de externa nycklar som är registrerade i din organisation

Exempel på begäran

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Exempel på svar

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

Validera en extern nyckel

Du kan använda den här slutpunkten för att kontrollera flera saker:

Att din externa molnkonfiguration fortfarande är giltig hos OpenAI efter att du har gjort ändringar (du får ett svar som visar att kontrollen lyckades).
Att din nyckel har återkallats korrekt, att återkallelsen behandlas av OpenAI och att den börjar gälla när cachelagringens TTL-tider på en timme har löpt ut (du får ett felsvar).

Exempel på begäran

curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Exempel på svar

{
  "status": "success"
}

Eller ett fel som kommer från molnleverantören.

Endpoints på projektnivå

Skapa ett nytt projekt med ett externt nyckel-ID

Detta är samma som den befintliga slutpunkten för att skapa projekt, men med parametern external_key_id tillagd i begäran och svaret.

Exempel på begäran

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

Exempel på svar

{
  "object": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[Begränsad åtkomst] Uppdatera ett befintligt projekt med ett externt nyckel-ID

Detta är samma som den befintliga slutpunkten för att uppdatera projekt, men med parametern external_key_id tillagd i begäran och svaret.

Vi rekommenderar att du skapar nya API-projekt för dina EKM-arbetsbelastningar. Om du vill använda EKM i alla dina befintliga API-projekt kan du kontakta din kundansvariga, så aktiverar vi funktionsflaggan för dig. Följ dessa rekommendationer innan du inför EKM i dina befintliga produktionsprojekt.

Testa först alla API-funktioner som du använder i produktion i ditt API-testprojekt med EKM.
Inför EKM stegvis i stället för att aktivera det i alla API-projekt i produktion samtidigt.

Exempel på begäran

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

Lista alla projekt i din organisation

Detta är samma som den befintliga slutpunkten, men med tillägget external_key_id i API-svaret.

Exempel på begäran

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Exempel på svar

{
  "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 (externa nycklar) i Management API

Sammanfattning

Åtkomst

Användning

Begränsningar

Endpoints på organisationsnivå

Registrera en extern nyckel för din organisation

AWS

GCP

Azure

Ta bort en extern nyckel som är registrerad i din organisation

Exempel på begäran

Exempel på svar

Hämta de externa nycklar som är registrerade i din organisation

Exempel på begäran

Exempel på svar

Validera en extern nyckel

Exempel på begäran

Exempel på svar

Endpoints på projektnivå

Skapa ett nytt projekt med ett externt nyckel-ID

Exempel på begäran

Exempel på svar

[Begränsad åtkomst] Uppdatera ett befintligt projekt med ett externt nyckel-ID

Exempel på begäran

Lista alla projekt i din organisation

Exempel på begäran

Exempel på svar

Var den här artikeln till hjälp?