OpenAI
Denne siden ble maskinoversatt. Se den opprinnelige engelske artikkelen.

EKM (eksterne nøkler) i Management API

Administrer eksterne nøkler for EKM med Management API

Oppdatert: yesterday

Sammendrag

Tilgang

  • EKM endpoints er tilgjengelige i Management API via en Admin API-nøkkel. https://platform.openai.com/settings/organization/admin-keys (ikke bruk en vanlig API-nøkkel). Admin API-nøkler er tilgjengelige for organisasjonseiere.

  • Bruk api.external_keys.write til å opprette eller slette eksterne nøkler, og api.external_keys.read til å liste opp eller validere eksterne nøkler. Én enkelt nøkkel trenger begge omfangene bare hvis den må utføre både lese- og skriveoperasjoner.

  • Vi må for øyeblikket aktivere organisasjonen din for disse endpoints med et funksjonsflagg. Du vet at funksjonsflagget er aktivert hvis du ser external_key_id returnert fra det eksisterende List Projects-endpoint: https://api.openai.com/v1/organization/projects

Bruk

Begrensninger

  • Du må først teste EKM på et nytt prosjekt via Management API.

  • Vi anbefaler å opprette nye prosjekter for EKM-arbeidsbelastningene dine. Hvis du likevel vil bruke EKM på et eksisterende prosjekt, kan vi legge deg til i funksjonsflagget. Merk deg følgende anbefalte praksis før du ruller ut EKM til eksisterende produksjonsprosjekter.

    • Test først alle API-funksjoner du bruker i produksjon, i EKM API-testprosjektet ditt

    • Bruk en gradvis utrulling i stedet for å aktivere EKM på alle API-produksjonsprosjekter samtidig

Endpoints på organisasjonsnivå

Registrer en ekstern nøkkel for organisasjonen din

AWS

Eksempelforespørsel

  • type: string –  alltid “aws”

  • name: string –  Et lettfattelig navn på konfigurasjonen din

  • role_arn: string – Role ARN som OpenAI skal anta i skyen din

  • kms_arn: string – Key Management System ARN for hovednøkkelen du administrerer

  • external_id: string – Organisasjons-ID-en din eller API-prosjekt-ID-en din

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

Eksempelforespørsel

  • type: string – alltid  "gcp",

  • name: string – Et lettfattelig navn på konfigurasjonen din

  • workload_identity_project_number: string – Det 12-sifrede GCP-prosjektnummeret der du registrerte OpenAI's Workload Identity

  • workload_identity_pool_id: string – Poolen som inneholder Workload Identity-leverandøren du registrerte for OpenAI

  • workload_identity_provider_id: string – Workload Identity-leverandøren du registrerte for OpenAI

  • audience: string – Målgruppen OpenAI skal sende i tokenet når vi antar en rolle gjennom GCP STS-en din

  • kms_project_id: string – Navnet på GCP-prosjektet der KMS-en din ligger

  • kms_key_ring_name: string – Key Management System-nøkkelringen som inneholder hovednøkkelen du administrerer

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

  • kms_key_location: string – Regionen der Key Management System-hovednøkkelen er plassert

Hvis KMS-en din ligger i et annet GCP-prosjekt enn det der du registrerte OpenAI's Workload Identity, må du sørge for at prosjektet som inneholder OpenAI's Workload Identity, i det minste har KMS aktivert ved å 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

Eksempelforespørsel

  • type: string – alltid  "azure",

  • name: string – Et lettfattelig navn på konfigurasjonen din

  • tenant_id: string – UUID-en til Azure-leieren din

  • vault_uri: string – URI-en til Azure-hvelvet som inneholder hovednøkkelen du administrerer

  • key_name: string – Navnet på Azure Key Vault-hovednøkkelen 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"
}

Slett en ekstern nøkkel som er registrert for organisasjonen din

Merk: Du kan bare slette en ekstern nøkkel hvis den ikke er knyttet til aktive API-prosjekter eller arbeidsområder. Hvis den er knyttet til et aktivt API-prosjekt, arkiverer du prosjektet først. Hvis den er knyttet til et arbeidsområde, kan nøkkelen ikke slettes.

Eksempelforespørsel

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øklene som er registrert for organisasjonen din

Eksempelforespørsel

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økkel

Du kan bruke dette endpoint til å kontrollere flere ting

  • Den eksterne skykonfigurasjonen din er fortsatt gyldig med OpenAI etter at du har gjort endringer (du får et vellykket svar)

  • Tilbakekallingen av nøkkelen er gjort riktig, behandles av OpenAI og trer i kraft når hurtigbuffer-TTL-ene på 1 time er utløpt (du får en feilmelding)

Eksempelforespørsel

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

Eksempelsvar

{
 "status": "success"
}

Eller en feil som ble meldt fra skyleverandøren.

Endpoints på prosjektnivå

Opprett et nytt prosjekt med en ekstern nøkkel-ID

Dette er det samme som det eksisterende Create Project-endpoint, med parameteren external_key_id lagt til i forespørselen og svaret.

Eksempelforespørsel

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

[Begrenset] Oppdater et eksisterende prosjekt med en ekstern nøkkel-ID

Dette er det samme som det eksisterende Update Project-endpoint, med parameteren external_key_id lagt til i forespørselen og svaret.


Vi anbefaler å opprette nye API-prosjekter for EKM-arbeidsbelastningene dine. Hvis du vil bruke EKM på alle eksisterende API-prosjekter, kan du spørre kundeansvarlig, så legger vi deg til i funksjonsflagget. Merk deg følgende anbefalte praksis før du ruller ut EKM til eksisterende produksjonsprosjekter.

  • Test først alle API-funksjoner du bruker i produksjon, i EKM API-testprosjektet ditt

  • Bruk en gradvis utrulling i stedet for å aktivere EKM på alle API-produksjonsprosjekter samtidig

Eksempelforespørsel

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

List opp alle prosjektene i organisasjonen din

Dette er det samme som det eksisterende endpoint, men med external_key_id lagt til i API-svaret

Eksempelforespørsel

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 artikkelen nyttig?