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

EKM (External Keys) in de Management API

Externe sleutels voor EKM beheren met de Management API

Bijgewerkt: 4 hours ago

Samenvatting

Toegang

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

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

  • We moeten je organisatie momenteel via een featureflag toegang geven tot deze endpoints. Je weet dat je featureflag actief is als je external_key_id terugziet van het bestaande endpoint List Projects: https://api.openai.com/v1/organization/projects

Gebruik

Beperkingen

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

  • We raden aan nieuwe projecten op te zetten voor je EKM-workloads. Als je EKM echter op een bestaand project wilt, kunnen we je toevoegen aan de featureflag. Let op de volgende best practices voordat je EKM uitrolt naar je bestaande productieprojecten.

    • Test eerst alle API-functies die je in productie gebruikt in je test-EKM-API-project

    • Gebruik een gefaseerde uitrol in plaats van EKM in één keer op alle productie-API-projecten in te vullen

Endpoints op organisatieniveau

Een externe sleutel bij je organisatie registreren

AWS

Voorbeeldaanvraag

  • type: string -  altijd "aws"

  • name: string -  Een herkenbare naam voor je configuratie

  • role_arn: string - De Role ARN die OpenAI in je cloud zal aannemen

  • kms_arn: string - De Key Management System ARN 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

Voorbeeldaanvraag

  • type: string - altijd  "gcp",

  • name: string - Een herkenbare naam voor je configuratie

  • workload_identity_project_number: string - Het 12-cijferige GCP-projectnummer waar 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 de 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 Key Management System-sleutelring met de hoofdsleutel die je beheert

  • kms_key_name: string - De naam van de Key Management System-hoofdsleutel

  • kms_key_location: string - De regio waar je Key Management System-hoofdsleutel 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 in ieder geval KMS is ingeschakeld voor het project met de Workload Identity van OpenAI via 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

Voorbeeldaanvraag

  • type: string - altijd  "azure",

  • name: string - Een herkenbare naam voor je configuratie

  • tenant_id: string - Je Azure-tenant-UUID

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

  • key_name: string - De naam van de Azure Key Vault-hoofdsleutel 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

Opmerking: Je kunt een externe sleutel alleen verwijderen als deze niet is gekoppeld aan actieve API-projecten of een werkruimte. Als deze is gekoppeld aan een actief API-project, archiveer dat project dan eerst. Als deze aan een werkruimte is gekoppeld, kan de sleutel niet worden verwijderd.

Voorbeeldaanvraag

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

Voorbeeldaanvraag

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

Je kunt dit endpoint gebruiken om verschillende zaken te controleren

  • Je externe cloudconfiguratie blijft geldig bij OpenAI nadat je wijzigingen hebt aangebracht (je krijgt een succesrespons)

  • Je sleutelintrekking is correct uitgevoerd, wordt door OpenAI verwerkt en wordt van kracht nadat de cache-TTL's van 1 uur zijn verlopen (je krijgt een foutrespons)

Voorbeeldaanvraag

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 maken met een externe sleutel-ID

Dit is hetzelfde als het bestaande endpoint Create Project, met toevoeging van de parameter external_key_id in de aanvraag en respons.

Voorbeeldaanvraag

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": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "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,
}

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

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


We raden aan nieuwe API-projecten op te zetten voor je EKM-workloads. Als je EKM op al je bestaande API-projecten wilt, vraag het je accountdirector en wij voegen je toe aan de featureflag. Let op de volgende best practices voordat je EKM uitrolt naar je bestaande productieprojecten.

  • Test eerst alle API-functies die je in productie gebruikt in je test-EKM-API-project

  • Gebruik een gefaseerde uitrol in plaats van EKM in één keer op alle productie-API-projecten in te vullen

Voorbeeldaanvraag

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 weergeven

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

Voorbeeldaanvraag

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?