OpenAI
Deze pagina is automatisch vertaald. Bekijk het oorspronkelijke Engelstalige artikel.

EKM (External Keys) in de Management API

Leer hoe je externe sleutels voor EKM beheert met de Management API.

Bijgewerkt: 9 minutes ago

Samenvatting

Toegang

  • EKM-endpoints zijn toegankelijk in de Management API met een API-beheerderssleutel. https://platform.openai.com/settings/organization/admin-keys (gebruik geen gewone API-sleutel). API-beheerderssleutels zijn beschikbaar voor organisatie-eigenaren.

  • Gebruik api.external_keys.write om externe sleutels aan te maken of te verwijderen en api.external_keys.read om externe sleutels weer te geven, op te halen of te valideren. Een sleutel heeft alleen beide scopes nodig als deze zowel lees- als schrijfbewerkingen moet uitvoeren.

Gebruik

  • Je EKM-configuratie wordt geregistreerd op het niveau van de organisatie via een nieuw endpoint: https://api.openai.com/v1/organization/external_keys.

  • Bij het registreren van je EKM-configuratie wordt een external_key_id geretourneerd in de vorm extkey_xxxx.

  • EKM-configuraties worden geactiveerd op het niveau van een project door een external_key_id mee te geven in de body van het verzoek aan het bestaande endpoint voor het aanmaken van een project: https://api.openai.com/v1/organization/projects.

Beperkingen

  • Je moet EKM eerst via de Management API testen op een nieuw project.

  • We raden aan nieuwe projecten aan te maken voor je EKM-workloads. Neem de volgende aanbevelingen door voordat je EKM uitrolt naar je bestaande productieprojecten.

    • Test alle API-functies die je in productie gebruikt eerst in je API-testproject met EKM.

    • Rol EKM geleidelijk uit in plaats van het in één keer voor alle API-productieprojecten in te stellen.

Endpoints op organisatieniveau

Een externe sleutel bij je organisatie registreren

AWS

Voorbeeldverzoek:

  • type: string - altijd "aws"

  • name: string - Een herkenbare naam voor je configuratie

  • role_arn: string - De ARN van de rol die OpenAI in je cloud zal aannemen

  • kms_arn: string - De ARN in het sleutelbeheersysteem voor de hoofdsleutel die je beheert

  • external_id: string - Je Organisatie-ID of API-project-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>"
}'

Voorbeeldrespons:

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

Voorbeeldverzoek:

  • type: string - altijd "gcp",

  • name: string - Een herkenbare naam voor je configuratie

  • workload_identity_project_number: string - Het numerieke nummer van het GCP-project waarin je de Workload Identity van OpenAI hebt geregistreerd

  • workload_identity_pool_id: string - De pool met de Workload Identity-provider die je voor OpenAI hebt geregistreerd

  • workload_identity_provider_id: string - De Workload Identity-provider die je voor OpenAI hebt geregistreerd

  • audience: string - De audience die OpenAI in het token moet meegeven wanneer we via je GCP STS een rol aannemen

  • kms_project_id: string - De naam van het GCP-project waarin je KMS zich bevindt

  • kms_key_ring_name: string - De sleutelring in het sleutelbeheersysteem met de hoofdsleutel die je beheert

  • kms_key_name: string - De naam van de hoofdsleutel in het sleutelbeheersysteem

  • kms_key_location: string - De regio waarin de hoofdsleutel van je sleutelbeheersysteem zich bevindt

Als je KMS zich in een ander GCP-project bevindt dan het project waarin je de Workload Identity van OpenAI hebt geregistreerd, zorg er dan voor dat KMS in elk geval is ingeschakeld voor het project met de Workload Identity van OpenAI. Ga hiervoor naar 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"
}'

Voorbeeldrespons:

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

Voorbeeldverzoek:

  • type: string - altijd "azure",

  • name: string - Een herkenbare naam voor je configuratie

  • tenant_id: string - De UUID van je Azure-tenant

  • vault_uri: string - De URI van de Azure-kluis met de hoofdsleutel die je beheert

  • key_name: string - De naam van de hoofdsleutel in Azure Key Vault die je beheert.

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

Voorbeeldrespons:

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

OCI

Stel een ingeschakelde AES-256-sleutel in en verleen OpenAI toegang. De sleutel moet een vrije tag openai_organization_id hebben met je Organisatie-ID bij OpenAI als waarde. Zie voor de configuratiestappen: OCI Vault configureren voor Enterprise Key Management.

Voorbeeldverzoek:

  • type: string - altijd "oci"

  • purpose: string - "ekm"; de standaardwaarde als deze parameter wordt weggelaten

  • name: string - Een herkenbare naam voor je configuratie

  • region: string - De OCI-regio waarin je kluis en sleutel zich bevinden

  • vault_ocid: string - De volledige OCID van je kluis

  • key_ocid: string - De volledige OCID van je AES-256-sleutel

Geef key_version_ocid niet mee voor EKM.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'

Voorbeeldrespons:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}

De API retourneert HTTP 200 als het verzoek slaagt. Sla de geretourneerde id op en gebruik deze als external_key_id wanneer je een project aanmaakt. De bestaande bewerkingen voor weergeven, ophalen, valideren en verwijderen zijn ook van toepassing op OCI-registraties.

Gebruik voor PSP-herstel een aparte RSA-3072-registratie met purpose: "psp_decryption" en een exacte key_version_ocid. Stel psp_decryption_key_id in op de bijbehorende OpenAI-registratie-ID. OpenAI heeft voor die RSA-sleutel alleen leestoegang nodig tot de metagegevens en openbare sleutels. Zie voor de volledige configuratie: Asymmetrische sleutels instellen — OCI Vault.

Een externe sleutel verwijderen die voor je organisatie is geregistreerd

Opmerking: Verwijderen wordt geblokkeerd zolang een actief project of een actieve werkruimte de registratie gebruikt. Archiveer voor EKM eerst de gekoppelde API-projecten; een EKM-registratie die aan een werkruimte is gekoppeld, blijft beschermd. Vervang of wis voor PSP-herstel psp_decryption_key_id in elk actief project dat naar de registratie verwijst voordat je de registratie verwijdert. Als je een OpenAI-registratie verwijdert, wordt de cloudsleutel niet verwijderd.

Voorbeeldverzoek

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

Voorbeeldrespons

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

De externe sleutels ophalen die voor je organisatie zijn geregistreerd

Zonder filter op purpose bevat de lijst zowel EKM-registraties als registraties voor PSP-herstel. Gebruik ?purpose=ekm of ?purpose=psp_decryption om op doel te filteren.

Voorbeeldverzoek

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

Voorbeeldrespons

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

Een externe sleutel valideren

Gebruik validatie om te controleren of OpenAI nog steeds toegang heeft tot je cloudsleutel.

  • Voor EKM controleert OpenAI of het met de sleutel kan versleutelen en ontsleutelen. Zie voor informatie over intrekking en caching: richtlijnen voor de levenscyclus van sleutels.

  • Voor PSP-herstel haalt OpenAI de openbare sleutel van de geregistreerde versie op en vergelijkt deze met de opgeslagen momentopname. Een geslaagde validatie bevestigt niet dat je herstelidentiteit kan ontsleutelen. Een mislukte validatie verwijdert of vervangt de opgeslagen momentopname van de openbare sleutel niet.

Als je een registratie ophaalt met GET, wordt de opgeslagen configuratie geretourneerd en wordt de toegang tot je cloudsleutel niet opnieuw gecontroleerd.

Voorbeeldverzoek

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

Voorbeeldrespons

{
"status": "success"
}

Of een fout die door de cloudprovider is gemeld.

Endpoints op projectniveau

Een nieuw project aanmaken met een externe sleutel-ID

Dit is hetzelfde als het bestaande endpoint voor het aanmaken van een project, maar met de toevoeging van de parameter external_key_id in het verzoek en de respons.

Voorbeeldverzoek

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

Voorbeeldrespons

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

Een bestaand project bijwerken met een externe sleutel-ID

Dit is hetzelfde als het bestaande endpoint Update Project, met als toevoeging de parameter external_key_id in het verzoek en de respons.

We raden aan nieuwe API-projecten aan te maken voor je EKM-workloads. Neem de volgende aanbevelingen door voordat je EKM uitrolt naar je bestaande productieprojecten.

  • Test alle API-functies die je in productie gebruikt eerst in je API-testproject met EKM.

  • Rol EKM geleidelijk uit in plaats van het in één keer voor alle API-productieprojecten in te stellen.

Voorbeeldverzoek

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

Alle projecten in je organisatie opsommen

Dit is hetzelfde als het bestaande endpoint, maar met de toevoeging van external_key_id in de API-respons.

Voorbeeldverzoek

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

Voorbeeldrespons

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

Was dit artikel nuttig?