Lær hvordan du administrerer eksterne nøkler for EKM med administrasjons-API-et.

Sammendrag

Tilgang

EKM-endepunkter er tilgjengelige i administrasjons-API-et med en administrator-API-nøkkel. https://platform.openai.com/settings/organization/admin-keys (ikke bruk en vanlig API-nøkkel). Administrator-API-nøkler er tilgjengelige for organisasjonseiere.
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 nøkkel trenger begge tilgangsområdene bare hvis den skal utføre både lese- og skriveoperasjoner.
Foreløpig må vi aktivere et funksjonsflagg for at organisasjonen din skal få tilgang til disse endepunktene. Du vet at funksjonsflagget er aktivert hvis external_key_id returneres fra det eksisterende endepunktet for å liste opp prosjekter: https://api.openai.com/v1/organization/projects.

Bruk

EKM-konfigurasjonen din registreres på organisasjonsnivå via et nytt endepunkt: https://api.openai.com/v1/organization/external_keys.
Når du registrerer EKM-konfigurasjonen, returneres en external_key_id på formen extkey_xxxx.
EKM-konfigurasjoner aktiveres på prosjektnivå ved å sende en external_key_id i forespørselskroppen til det eksisterende endepunktet for å opprette prosjekter: https://api.openai.com/v1/organization/projects.

Begrensninger

Du må først teste EKM på et nytt prosjekt via administrasjons-API-et.
Vi anbefaler å opprette nye prosjekter for EKM-arbeidslastene dine. Hvis du likevel vil ha EKM på et eksisterende prosjekt, kan vi aktivere funksjonsflagget for deg. Følg disse anbefalingene før du ruller ut EKM til eksisterende produksjonsprosjekter.
- Test først alle API-funksjonene du bruker i produksjon, i API-testprosjektet ditt med EKM.
- Rull ut gradvis i stedet for å aktivere EKM på alle API-prosjekter i produksjon samtidig.

Endpoints på organisasjonsnivå

Registrer en ekstern nøkkel for organisasjonen din

AWS

Eksempel på forespørsel:

type: streng – alltid «aws»
name: streng – Et lett gjenkjennelig navn på konfigurasjonen
role_arn: streng – ARN-en til rollen som OpenAI skal påta seg i skymiljøet ditt
kms_arn: streng – ARN-en i nøkkelhåndteringssystemet for hovednøkkelen du administrerer
external_id: streng – 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>"
}'

Eksempel 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

Eksempel på forespørsel:

type: streng – alltid «gcp»,
name: streng – Et lett gjenkjennelig navn på konfigurasjonen
workload_identity_project_number: streng – Det numeriske prosjektnummeret i GCP der du registrerte OpenAIs arbeidslastidentitet
workload_identity_pool_id: streng – Poolen som inneholder Workload Identity-leverandøren du registrerte for OpenAI
workload_identity_provider_id: streng – Workload Identity-leverandøren du registrerte for OpenAI
audience: streng – Mottakeren som OpenAI skal angi i tokenet når vi påtar oss en rolle via din GCP STS
kms_project_id: streng – Navnet på GCP-prosjektet der KMS-et ditt ligger
kms_key_ring_name: streng – Nøkkelringen i nøkkelhåndteringssystemet som inneholder hovednøkkelen du administrerer
kms_key_name: streng – Navnet på hovednøkkelen i nøkkelhåndteringssystemet
kms_key_location: streng – Regionen der hovednøkkelen i nøkkelhåndteringssystemet ditt ligger

Hvis KMS-et ditt 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, i det minste har KMS aktivert. Det gjør du 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"
}'

Eksempel 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

Eksempel på forespørsel:

type: streng – alltid «azure»,
name: streng – Et lett gjenkjennelig navn på konfigurasjonen
tenant_id: streng – UUID-en til Azure-leieren din
vault_uri: streng – URI-en til Azure-hvelvet som inneholder hovednøkkelen du administrerer
key_name: streng – Navnet på hovednøkkelen i Azure Key Vault som du administrerer.
- Det må ha formen <org-xxx>--<any_name>
- der org-xxx er Organisasjons-ID-en din hos OpenAI, som du finner 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"
}'

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

Slett en ekstern nøkkel som er registrert på organisasjonen din

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

Eksempel på forespørsel

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

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

Hent de eksterne nøklene som er registrert på organisasjonen din

Eksempel på forespørsel

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

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

Valider en ekstern nøkkel

Du kan bruke dette endepunktet til å kontrollere flere ting:

At den eksterne skykonfigurasjonen din fortsatt er gyldig hos OpenAI etter at du har gjort endringer (du får et svar som bekrefter at valideringen var vellykket).
At tilbakekallingen av nøkkelen er utført riktig, behandles av OpenAI og trer i kraft når hurtigbufferens levetider (TTL) på én time har utløpt (du får et feilsvar).

Eksempel på forespørsel

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

Eksempel på svar

{
  "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 endepunktet for å opprette prosjekter, men med parameteren external_key_id lagt til i forespørselen og svaret.

Eksempel på forespø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"
}'

Eksempel på svar

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

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

Dette er det samme som det eksisterende endepunktet for å oppdatere prosjekter, men med parameteren external_key_id lagt til i forespørselen og svaret.

Vi anbefaler å opprette nye API-prosjekter for EKM-arbeidslastene dine. Hvis du vil ha EKM på alle eksisterende API-prosjekter, kan du kontakte kundeansvarlig, så aktiverer vi funksjonsflagget for deg. Følg disse anbefalingene før du ruller ut EKM til eksisterende produksjonsprosjekter.

Test først alle API-funksjonene du bruker i produksjon, i API-testprosjektet ditt med EKM.
Rull ut gradvis i stedet for å aktivere EKM på alle API-prosjekter i produksjon samtidig.

Eksempel på forespø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 external_key_id lagt til i API-svaret.

Eksempel på forespørsel

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

Eksempel 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 (eksterne nøkler) i Management API

Sammendrag

Tilgang

Bruk

Begrensninger

Endpoints på organisasjonsnivå

Registrer en ekstern nøkkel for organisasjonen din

AWS

GCP

Azure

Slett en ekstern nøkkel som er registrert på organisasjonen din

Eksempel på forespørsel

Eksempel på svar

Hent de eksterne nøklene som er registrert på organisasjonen din

Eksempel på forespørsel

Eksempel på svar

Valider en ekstern nøkkel

Eksempel på forespørsel

Eksempel på svar

Endpoints på prosjektnivå

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

Eksempel på forespørsel

Eksempel på svar

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

Eksempel på forespørsel

List opp alle prosjektene i organisasjonen din

Eksempel på forespørsel

Eksempel på svar

Var denne artikkelen nyttig?