OpenAI
Den här sidan har maskinöversatts. Visa den ursprungliga engelska artikeln.

EKM (externa nycklar) i Management API

Hantera externa nycklar för EKM med Management API

Uppdaterades: 14 days ago

Sammanfattning

Åtkomst

  • EKM-endpoints är åtkomliga i Management API via en Admin API-nyckel. https://platform.openai.com/settings/organization/admin-keys (använd inte en vanlig API-nyckel). Admin API-nycklar ä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 omfattningarna endast om den måste utföra både läs- och skrivåtgärder.

  • För närvarande behöver vi ge din organisation åtkomst till dessa endpoints via en funktionsflagga. Du vet att du har funktionsflaggan om du ser external_key_id returneras från den befintliga List Projects-endpointen: https://api.openai.com/v1/organization/projects

Användning

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. Men om du vill använda EKM i ett befintligt projekt kan vi lägga till dig i funktionsflaggan. Observera följande bästa praxis innan du rullar ut EKM till dina befintliga produktionsprojekt.

    • Testa först alla API-funktioner som du använder i produktion i ditt EKM-testprojekt för API

    • Rulla ut gradvis i stället för att aktivera EKM i alla produktions-API-projekt på en gång

Endpoints på organisationsnivå

Registrera en extern nyckel för din organisation

AWS

Exempelbegäran

  • type: string – alltid ”aws”

  • name: string – ett lättläst namn för din konfiguration

  • role_arn: string – den Role ARN som OpenAI ska anta i ditt moln

  • kms_arn: string – Key Management System-ARN för huvudnyckeln du hanterar

  • external_id: string – 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>
}'

Exempelsvar

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

Exempelbegäran

  • type: string – alltid ”gcp”,

  • name: string – ett lättläst namn för din konfiguration

  • workload_identity_project_number: string – det 12-siffriga GCP-projektnumret där du registrerade OpenAI:s Workload Identity

  • workload_identity_pool_id: string – poolen som innehåller den Workload Identity-provider som du registrerade för OpenAI

  • workload_identity_provider_id: string – den Workload Identity-provider som du registrerade för OpenAI

  • audience: string – den målgrupp som OpenAI ska skicka i token när vi antar en roll via din GCP STS

  • kms_project_id: string – namnet på GCP-projektet där din KMS finns

  • kms_key_ring_name: string – Key Management System-nyckelringen som innehåller huvudnyckeln du hanterar

  • kms_key_name: string – namnet på Key Management System-huvudnyckeln

  • kms_key_location: string – regionen där din Key Management System-huvudnyckel finns

Om din KMS finns i ett annat GCP-projekt än det där du registrerade OpenAI:s Workload Identity, se till att projektet som innehåller OpenAI:s Workload Identity åtminstone har KMS aktiverat 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"
}'

Exempelsvar

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

Exempelbegäran

  • type: string – alltid ”azure”,

  • name: string – ett lättläst namn för din konfiguration

  • tenant_id: string – din UUID för Azure-klientorganisationen

  • vault_uri: string – URI:n för det Azure-valv som innehåller huvudnyckeln du hanterar

  • key_name: string – namnet på Azure Key Vault-huvudnyckeln som du hanterar.

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

Exempelsvar

{
  "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 registrerats för din organisation

Obs! Du kan bara ta bort en extern nyckel om den inte är kopplad till några aktiva API-projekt eller någon Arbetsyta. Om den är kopplad till ett aktivt API-projekt arkiverar du projektet först. Om den är kopplad till en Arbetsyta går nyckeln inte att ta bort.

Exempelbegäran

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

Exempelsvar

{
  "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 för din organisation

Exempelbegäran

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

Exempelsvar

{
  "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 denna endpoint för att kontrollera flera saker

  • Din externa molnkonfiguration förblir giltig hos OpenAI efter att du har gjort ändringar (du får ett svar om att åtgärden lyckades)

  • Din nyckelåterkallelse är korrekt utförd, behandlas av OpenAI och träder i kraft när cachelagringens TTL på 1 timme har löpt ut (du får ett felsvar)

Exempelbegäran

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

Exempelsvar

{
 "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 Create Project-endpointen, med tillägget parametern external_key_id i begäran och svaret.

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

Exempelsvar

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

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

Detta är samma som den befintliga Update Project-endpointen, med tillägget parametern external_key_id 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 kontaktar du din account director, så lägger vi till dig i funktionsflaggan. Observera följande bästa praxis innan du rullar ut EKM till dina befintliga produktionsprojekt.

  • Testa först alla API-funktioner som du använder i produktion i ditt EKM-testprojekt för API

  • Rulla ut gradvis i stället för att aktivera EKM i alla produktions-API-projekt på en gång

Exempelbegä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 endpointen, men med tillägget external_key_id i API-svaret

Exempelbegäran

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

Exempelsvar

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

Var den här artikeln till hjälp?