Oversigt

Adgang

EKM-endepunkter er tilgængelige i Management API via en administrator-API-nøgle. https://platform.openai.com/settings/organization/admin-keys (brug ikke en almindelig API-nøgle). Administrator-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 nøgle behøver kun begge rettighedsområder, hvis den skal udføre både læse- og skriveoperationer.
Vi skal i øjeblikket aktivere et funktionsflag, før din organisation kan få adgang til disse endepunkter. Du kan se, at funktionsflaget er aktiveret, hvis external_key_id returneres fra det eksisterende endepunkt til at vise projekter: https://api.openai.com/v1/organization/projects.

Brug

Din EKM-konfiguration registreres for hele organisationen via et nyt endepunkt: https://api.openai.com/v1/organization/external_keys.
Når du registrerer din EKM-konfiguration, returneres et external_key_id i formatet extkey_xxxx.
EKM-konfigurationer aktiveres for det enkelte projekt ved at sende et external_key_id i anmodningens indhold til det eksisterende endepunkt til at oprette projekter: https://api.openai.com/v1/organization/projects.

Begrænsninger

Du skal først teste EKM i et nyt projekt via Management API.
Vi anbefaler, at du opretter nye projekter til dine EKM-workloads. Hvis du alligevel vil bruge EKM i et eksisterende projekt, kan vi aktivere funktionsflaget for dig. Følg disse anbefalinger, før du udruller EKM til dine eksisterende produktionsprojekter.
- Test først alle de API-funktioner, du bruger i produktion, i dit API-testprojekt med EKM.
- Udrul EKM gradvist i stedet for at aktivere det i alle API-projekter i produktion på én gang.

End points på organisationsniveau

Registrer en ekstern nøgle i din organisation

AWS

Eksempel på anmodning:

type: streng – altid »aws«
name: streng – Et letgenkendeligt navn til din konfiguration
role_arn: streng – ARN for den rolle, som OpenAI påtager sig i dit cloudmiljø
kms_arn: streng – ARN i nøgleadministrationssystemet for den hovednøgle, du administrerer
external_id: streng – 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>"
}'

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å anmodning:

type: streng – altid »gcp«,
name: streng – Et letgenkendeligt navn til din konfiguration
workload_identity_project_number: streng – Det numeriske projektnummer for det GCP-projekt, hvor du registrerede OpenAI's workloadidentitet
workload_identity_pool_id: streng – Den pulje, der indeholder den Workload Identity-udbyder, du registrerede for OpenAI
workload_identity_provider_id: streng – Den Workload Identity-udbyder, du registrerede for OpenAI
audience: streng – Den målgruppe, OpenAI skal angive i tokenet, når vi påtager os en rolle via din GCP STS
kms_project_id: streng – Navnet på det GCP-projekt, hvor dit KMS er placeret
kms_key_ring_name: streng – Den nøglering i nøgleadministrationssystemet, der indeholder den hovednøgle, du administrerer
kms_key_name: streng – Navnet på hovednøglen i nøgleadministrationssystemet
kms_key_location: streng – Den region, hvor hovednøglen i dit nøgleadministrationssystem er placeret

Hvis dit KMS er placeret i et andet GCP-projekt end det, hvor du registrerede OpenAI's Workload Identity, skal du sikre dig, at KMS som minimum er aktiveret i projektet med OpenAI's Workload Identity. Det gør du 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"
}'

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å anmodning:

type: streng – altid »azure«,
name: streng – Et letgenkendeligt navn til din konfiguration
tenant_id: streng – UUID'et for din Azure-lejer
vault_uri: streng – URI'en for den Azure-nøgleboks, der indeholder den hovednøgle, du administrerer
key_name: streng – Navnet på den hovednøgle i Azure Key Vault, du administrerer.
- Det skal have formatet <org-xxx>--<any_name>
- hvor org-xxx er dit OpenAI-organisations-id, som du kan finde 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"
}

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 et arbejdsområde. Hvis den er knyttet til et aktivt API-projekt, skal du først arkivere projektet. Hvis den er knyttet til et arbejdsområde, kan nøglen ikke slettes.

Eksempel på anmodning

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øgler, der er registreret i din organisation

Eksempel på anmodning

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

Du kan bruge dette endepunkt til at kontrollere flere ting:

At din eksterne cloudkonfiguration stadig er gyldig hos OpenAI, efter at du har foretaget ændringer (du får et svar, der bekræfter, at valideringen lykkedes).
At din nøgle er tilbagekaldt korrekt, at tilbagekaldelsen behandles af OpenAI, og at den træder i kraft, når cachernes levetid (TTL) på 1 time er udløbet (du får et fejlsvar).

Eksempel på anmodning

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 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 endepunkt til at oprette projekter, men med parameteren external_key_id tilføjet i anmodningen og svaret.

Eksempel på anmodning

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

[Begrænset adgang] Opdater et eksisterende projekt med et eksternt nøgle-id

Dette er det samme som det eksisterende endepunkt til at opdatere projekter, men med parameteren external_key_id tilføjet i anmodningen og svaret.

Vi anbefaler, at du opretter nye API-projekter til dine EKM-workloads. Hvis du vil bruge EKM i alle dine eksisterende API-projekter, skal du kontakte din kundeansvarlige, så aktiverer vi funktionsflaget for dig. Følg disse anbefalinger, før du udruller EKM til dine eksisterende produktionsprojekter.

Test først alle de API-funktioner, du bruger i produktion, i dit API-testprojekt med EKM.
Udrul EKM gradvist i stedet for at aktivere det i alle API-projekter i produktion på én gang.

Eksempel på anmodning

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 endepunkt, men med external_key_id tilføjet i API-svaret.

Eksempel på anmodning

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øgler) i Management API

Oversigt

Adgang

Brug

Begrænsninger

End points på organisationsniveau

Registrer en ekstern nøgle i din organisation

AWS

GCP

Azure

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

Eksempel på anmodning

Eksempel på svar

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

Eksempel på anmodning

Eksempel på svar

Valider en ekstern nøgle

Eksempel på anmodning

Eksempel på svar

End points på projektniveau

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

Eksempel på anmodning

Eksempel på svar

[Begrænset adgang] Opdater et eksisterende projekt med et eksternt nøgle-id

Eksempel på anmodning

Vis alle projekter i din organisation

Eksempel på anmodning

Eksempel på svar

Var denne artikel nyttig?