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: 48 minutes ago

Samenvatting

Toegang

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

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

  • Momenteel moeten we deze endpoints via een featureflag beschikbaar maken voor je organisatie. Je weet dat de featureflag is ingeschakeld als het bestaande endpoint voor het opsommen van projecten external_key_id retourneert: https://api.openai.com/v1/organization/projects.

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. Als je EKM toch voor een bestaand project wilt gebruiken, kunnen we de featureflag voor je inschakelen. Neem de volgende aanbevolen werkwijzen in acht voordat je EKM uitrolt naar je bestaande productieprojecten.

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

    • Rol EKM geleidelijk uit in plaats van het in één keer voor alle API-projecten in productie in te schakelen.

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

Een externe sleutel verwijderen die bij je organisatie is geregistreerd

Let op: Je kunt een externe sleutel alleen verwijderen als deze niet is gekoppeld aan een actief API-project of een werkruimte. Als de sleutel aan een actief API-project is gekoppeld, archiveer dat project dan eerst. Als de sleutel aan een werkruimte is gekoppeld, kan deze niet worden 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 bij je organisatie zijn geregistreerd

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

Met dit endpoint kun je verschillende zaken controleren:

  • Of je externe cloudconfiguratie na wijzigingen nog steeds geldig is voor gebruik met OpenAI (je krijgt een succesrespons).

  • Of je sleutel correct is ingetrokken, de intrekking door OpenAI wordt verwerkt en van kracht wordt zodra de cache-TTL's van 1 uur zijn verlopen (je krijgt een foutrespons).

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

[Beperkt toegankelijk] Een bestaand project bijwerken met een externe sleutel-ID

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

We raden aan nieuwe API-projecten aan te maken voor je EKM-workloads. Als je EKM wilt gebruiken voor al je bestaande API-projecten, vraag dit dan aan je accountdirecteur. We schakelen de featureflag dan voor je in. Neem de volgende aanbevolen werkwijzen in acht voordat je EKM uitrolt naar je bestaande productieprojecten.

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

  • Rol EKM geleidelijk uit in plaats van het in één keer voor alle API-projecten in productie in te schakelen.

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?