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: 4 hours ago

Sammendrag

Tilgang

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

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

  • For øyeblikket må vi aktivere et feature flag for organisasjonen din for disse endepunktene. Du vet at du har feature flag-et hvis du ser **external_key_id **returnert fra det eksisterende List Projects-endepunktet: 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-arbeidslastene dine. Hvis du imidlertid vil ha EKM på et eksisterende prosjekt, kan vi legge deg til i feature flag-et. Merk følgende anbefalte fremgangsmåter før du ruller ut EKM til eksisterende produksjonsprosjekter.

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

    • Bruk en gradvis utrulling i stedet for å fylle inn EKM på alle produksjons-API-prosjekter samtidig

Endepunkter på organisasjonsnivå

Registrer en ekstern nøkkel i organisasjonen din

AWS

Eksempelforespørsel

  • type: string - alltid “aws”

  • name: string - Et lett gjenkjennelig navn for konfigurasjonen din

  • role_arn: string - Rolle-ARN-en som OpenAI vil overta i skyen din

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

  • external_id: string - Organisasjons-ID-en 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 lett gjenkjennelig navn for konfigurasjonen din

  • workload_identity_project_number: string - Det 12-sifrede GCP-prosjektnummeret der du registrerte OpenAIs arbeidslastidentitet

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

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

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

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

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

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

  • kms_key_location: string - Regionen der hovednøkkelen i Key Management System befinner seg

Hvis KMS-en din ligger i et annet GCP-prosjekt enn det der du registrerte OpenAIs Workload Identity, må du sørge for at prosjektet som inneholder OpenAIs Workload Identity, minst 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 lett gjenkjennelig navn for konfigurasjonen din

  • tenant_id: string - Azure-tenantens UUID

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

  • key_name: string - Navnet på Azure Key Vault-hovednøkkelen som 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 i organisasjonen din

Merk: Du kan bare slette en ekstern nøkkel hvis den ikke er knyttet til noen aktive prosjekter. Hvis den er knyttet til et aktivt prosjekt, må du først arkivere prosjektet.

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 i 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 endepunktet til å sjekke flere ting

  • At den eksterne skykonfigurasjonen din fortsatt er gyldig med OpenAI etter at du har gjort endringer (du vil se et svar om suksess)

  • At tilbakekallingen av nøkkelen er gjort riktig, behandles av OpenAI og trer i kraft etter at cache-TTL-ene på 1 time har utløpt (du vil se et feilsvar)

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 kommer fra skyleverandøren.

Endepunkter på prosjektnivå

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

Dette er det samme som det eksisterende Create Project-endepunktet, med tillegg av parameteren external_key_id 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": "Et prosjekt",
   "external_key_id": "extkey_xxxx"
}'

Eksempelsvar

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Et prosjekt",
  "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-endepunktet, med tillegg av parameteren external_key_id i forespørselen og svaret.

Vi anbefaler å opprette nye API-prosjekter for EKM-arbeidslastene dine. Hvis du vil ha EKM på alle de eksisterende API-prosjektene dine, kan du spørre kontodirektøren din, så legger vi deg til i feature flag-et. Merk følgende anbefalte fremgangsmåter før du ruller ut EKM til eksisterende produksjonsprosjekter.

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

  • Bruk en gradvis utrulling i stedet for å fylle inn EKM på alle produksjons-API-prosjekter 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 endepunktet, men med tillegg av external_key_id 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": "Prosjektnavn",
      "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?