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

EKM (externe sleutels) in de Management API

Beheer externe sleutels voor EKM met de Management API

Bijgewerkt: 13 days ago

Samenvatting

Toegang

  • EKM-endpoints zijn toegankelijk in de Management API via een Admin API Key. https://platform.openai.com/settings/organization/admin-keys (gebruik geen normale API-sleutel). Admin API keys 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. Eén sleutel heeft beide scopes alleen nodig als deze zowel lees- als schrijfbewerkingen moet uitvoeren.

  • We moeten momenteel een featureflag voor je organisatie inschakelen voor deze endpoints. Je weet dat je de featureflag hebt als je **external_key_id **ziet terugkomen 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. Houd rekening met de volgende best practices voordat je EKM uitrolt naar je bestaande productieprojecten.

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

    • Pas een geleidelijke uitrol toe in plaats van EKM in één keer op alle productie-API-projecten te vullen

Endpoints op organisatieniveau

Registreer een externe sleutel voor je organisatie

AWS

Voorbeeldaanvraag

  • type: string - altijd “aws”

  • name: string - Een gebruiksvriendelijke 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 gebruiksvriendelijke naam voor je configuratie

  • workload_identity_project_number: string - Het 12-cijferige GCP-projectnummer 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 meesturen 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 het project met de Workload Identity van OpenAI op zijn minst KMS is ingeschakeld door naar https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview te gaan

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 gebruiksvriendelijke naam voor je configuratie

  • tenant_id: string - Je Azure-tenant-UUID

  • vault_uri: string - De URI van de Azure-vault die de hoofdsleutel bevat 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"
}

Verwijder een externe sleutel die voor je organisatie is geregistreerd

Opmerking: Je kunt een externe sleutel alleen verwijderen als deze niet is gekoppeld aan actieve projecten. Als deze is gekoppeld aan een actief project, moet je dat project eerst archiveren.

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

Haal de externe sleutels op die voor 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"
}

Valideer een externe sleutel

Je kunt dit endpoint gebruiken om verschillende zaken te controleren

  • Of je externe cloudconfiguratie na wijzigingen geldig blijft voor OpenAI (je ziet een succesrespons)

  • Of het intrekken van je sleutel correct is uitgevoerd, door OpenAI wordt verwerkt, en van kracht wordt nadat de cache-TTL's van 1 uur zijn verlopen (je ziet 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 afkomstig is van de cloudprovider.

Endpoints op projectniveau

Maak een nieuw project 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] Werk een bestaand project bij 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 dan aan je accountdirecteur en we voegen je toe aan de featureflag. Houd rekening met de volgende best practices voordat je EKM uitrolt naar je bestaande productieprojecten.

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

  • Pas een geleidelijke uitrol toe in plaats van EKM in één keer op alle productie-API-projecten 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"
}'

Geef alle projecten in je organisatie weer

Dit is hetzelfde als het bestaande endpoint, maar met toevoeging van external_key_id in 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?