OpenAI
Denne side er maskinoversat. Se den originale engelske artikel.

EKM (eksterne nøgler) i Management API

Administrer eksterne nøgler til EKM med Management API

Opdateret: 14 days ago

Oversigt

Adgang

  • EKM-endpoints er tilgængelige i Management API via en Admin API Key. https://platform.openai.com/settings/organization/admin-keys (brug ikke en almindelig API-nøgle). Admin API-nøgler er tilgængelige for organisationsejere.

  • Brug api.external_keys.write til at oprette eller slette eksterne nøgler og api.external_keys.read til at vise eller validere eksterne nøgler. En enkelt nøgle behøver kun begge scopes, hvis den skal udføre både læse- og skrivehandlinger.

  • Vi skal i øjeblikket give din organisation adgang til disse endpoints via feature flag. Du ved, at du har feature flaget, hvis du ser external_key_id returneret fra det eksisterende List Projects-endpoint: https://api.openai.com/v1/organization/projects

Brug

Begrænsninger

  • Du skal først teste EKM på et nyt projekt via Management API.

  • Vi anbefaler at oprette nye projekter til dine EKM-workloads. Men hvis du vil bruge EKM på et eksisterende projekt, kan vi føje dig til feature flaget. Bemærk følgende best practices, før du udruller EKM til dine eksisterende produktionsprojekter.

    • Test først alle API-funktioner, som du bruger i produktion, i dit EKM API-testprojekt

    • Udrul gradvist i stedet for at aktivere EKM på alle produktions-API-projekter på én gang

End points på organisationsniveau

Registrer en ekstern nøgle i din organisation

AWS

Eksempelanmodning

  • type: string - altid “aws”

  • name: string - et brugervenligt navn til din konfiguration

  • role_arn: string - Den rolle-ARN, som OpenAI antager i din cloud

  • kms_arn: string - Key Management System-ARN for den hovednøgle, du administrerer

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

Eksempelsvar

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

Eksempelanmodning

  • type: string - altid "gcp",

  • name: string - et brugervenligt navn til din konfiguration

  • workload_identity_project_number: string - Det 12-cifrede GCP-projektnummer, hvor du registrerede OpenAI's workload identity

  • workload_identity_pool_id: string - Den pool, der indeholder den Workload Identity-udbyder, du registrerede for OpenAI

  • workload_identity_provider_id: string - Den Workload Identity-udbyder, du registrerede for OpenAI

  • audience: string - Den audience, som OpenAI skal sende i tokenet, når vi antager en rolle via din GCP STS

  • kms_project_id: string - Navnet på det GCP-projekt, hvor din KMS findes

  • kms_key_ring_name: string - Den Key Management System-nøglering, der indeholder den hovednøgle, du administrerer

  • kms_key_name: string - Navnet på Key Management System-hovednøglen

  • kms_key_location: string - Den region, hvor din Key Management System-hovednøgle er placeret

Hvis din KMS findes i et andet GCP-projekt end det, hvor du registrerede OpenAI's Workload Identity, skal du sikre, at projektet med OpenAI's Workload Identity som minimum har KMS aktiveret, ved at gå til 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"
}'

Eksempelsvar

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

Eksempelanmodning

  • type: string - altid "azure",

  • name: string - et brugervenligt navn til din konfiguration

  • tenant_id: string - UUID for din Azure-tenant

  • vault_uri: string - URI'en for den Azure-vault, der indeholder den hovednøgle, du administrerer

  • key_name: string - Navnet på den Azure Key Vault-hovednøgle, du administrerer.

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

Eksempelsvar

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

Slet en ekstern nøgle, der er registreret i din organisation

Bemærk: Du kan kun slette en ekstern nøgle, hvis den ikke er knyttet til aktive API-projekter eller arbejdsområde. Hvis den er knyttet til et aktivt API-projekt, skal du arkivere projektet først. Hvis den er knyttet til et arbejdsområde, kan nøglen ikke slettes.

Eksempelanmodning

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

Eksempelsvar

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

Hent de eksterne nøgler, der er registreret i din organisation

Eksempelanmodning

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

Eksempelsvar

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

Valider en ekstern nøgle

Du kan bruge dette endpoint til at kontrollere flere ting

  • Din eksterne cloudkonfiguration er stadig gyldig hos OpenAI, efter du har foretaget ændringer (du får et succes-svar)

  • Din nøgle tilbagekaldes korrekt, behandles af OpenAI og træder i kraft, når cache-TTL på 1 time er udløbet (du får et fejlsvar)

Eksempelanmodning

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

Eksempelsvar

{
 "status": "success"
}

Eller en fejl, der blev returneret fra cloududbyderen.

End points på projektniveau

Opret et nyt projekt med et eksternt nøgle-id

Dette er det samme som det eksisterende Create Project-endpoint, men med tilføjelse af parameteren external_key_id i anmodningen og svaret.

Eksempelanmodning

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

Eksempelsvar

{
  "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ænset] Opdater et eksisterende projekt med et eksternt nøgle-id

Dette er det samme som det eksisterende Update Project-endpoint, men med tilføjelse af parameteren external_key_id i anmodningen og svaret.


Vi anbefaler at oprette nye API-projekter til dine EKM-workloads. Hvis du vil bruge EKM på alle dine eksisterende API-projekter, skal du kontakte din account director, så føjer vi dig til feature flaget. Bemærk følgende best practices, før du udruller EKM til dine eksisterende produktionsprojekter.

  • Test først alle API-funktioner, som du bruger i produktion, i dit EKM API-testprojekt

  • Udrul gradvist i stedet for at aktivere EKM på alle produktions-API-projekter på én gang

Eksempelanmodning

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

Vis alle projekter i din organisation

Dette er det samme som det eksisterende endpoint, men med tilføjelse af external_key_id i API-svaret

Eksempelanmodning

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

Eksempelsvar

{
  "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 denne artikel nyttig?