OpenAI
Aquesta pàgina s'ha traduït automàticament. Mostra l'article original en anglès.

EKM (claus externes) a la Management API

Gestioneu claus externes per a EKM amb la Management API

Actualització: yesterday

Resum

Accés

  • Els endpoints d’EKM són accessibles a la Management API mitjançant una Admin API Key. https://platform.openai.com/settings/organization/admin-keys (no feu servir una clau d’API normal). Les claus d’API d’administrador estan disponibles per als propietaris de l’organització.

  • Feu servir api.external_keys.write per crear o suprimir claus externes, i api.external_keys.read per llistar o validar claus externes. Una sola clau només necessita tots dos àmbits si ha de fer operacions de lectura i d’escriptura.

  • Actualment hem d’activar aquests endpoints per a la vostra organització amb una marca de funcionalitat. Sabeu que teniu la marca de funcionalitat si veieu que l’endpoint List Projects existent retorna external_key_id : https://api.openai.com/v1/organization/projects

Ús

Restriccions

  • Primer heu de provar EKM en un projecte nou mitjançant la Management API.

  • Recomanem crear projectes nous per a les vostres càrregues de treball d’EKM. Tanmateix, si voleu EKM en un projecte existent, us podem afegir a la marca de funcionalitat. Tingueu en compte les pràctiques recomanades següents abans de desplegar EKM als vostres projectes de producció existents.

    • Proveu primer totes les funcions d’API que feu servir en producció al vostre projecte d’API EKM de prova

    • Feu un desplegament gradual en lloc d’afegir EKM a tots els projectes d’API de producció alhora

endpoints de nivell d’organització

Registrar una clau externa a la vostra organització

AWS

Sol·licitud d’exemple

  • type: string -  sempre “aws”

  • name: string -  Un nom descriptiu per a la vostra configuració

  • role_arn: string - L’ARN del rol que OpenAI assumirà al vostre núvol

  • kms_arn: string - L’ARN del sistema de gestió de claus per a la clau mestra que gestioneu

  • external_id: string - L’ID de la vostra organització o del projecte d’API

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

Resposta d’exemple

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

Sol·licitud d’exemple

  • type: string - sempre  "gcp",

  • name: string - Un nom descriptiu per a la vostra configuració

  • workload_identity_project_number: string - El número de projecte GCP de 12 dígits on heu registrat la identitat de càrrega de treball d’OpenAI

  • workload_identity_pool_id: string - L’agrupació que conté el proveïdor de Workload Identity que heu registrat per a OpenAI

  • workload_identity_provider_id: string - El proveïdor de Workload Identity que heu registrat per a OpenAI

  • audience: string - El públic que OpenAI ha de passar al segment quan assumim un rol mitjançant el vostre STS de GCP

  • kms_project_id: string - El nom del projecte GCP on es troba el vostre KMS

  • kms_key_ring_name: string - L’anell de claus del sistema de gestió de claus que conté la clau mestra que gestioneu

  • kms_key_name: string - El nom de la clau mestra del sistema de gestió de claus

  • kms_key_location: string - La regió on es troba la clau mestra del sistema de gestió de claus

Si el vostre KMS es troba en un projecte GCP diferent del projecte on heu registrat la Workload Identity d’OpenAI, assegureu-vos que el projecte que conté la Workload Identity d’OpenAI tingui com a mínim KMS activat accedint a 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"
}'

Resposta d’exemple

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

Sol·licitud d’exemple

  • type: string - sempre  "azure",

  • name: string - Un nom descriptiu per a la vostra configuració

  • tenant_id: string - L’UUID del vostre inquilí d’Azure

  • vault_uri: string - L’URI del magatzem d’Azure que conté la clau mestra que gestioneu

  • key_name: string - El nom de la clau mestra d’Azure Key Vault que gestioneu.

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

Resposta d’exemple

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

Suprimir una clau externa registrada a la vostra organització

Nota: només podeu suprimir una clau externa si no està associada a cap projecte d’API actiu ni a cap espai de treball. Si està associada a un projecte d’API actiu, arxiveu primer aquest projecte. Si està associada a un espai de treball, la clau no es pot suprimir.

Sol·licitud d’exemple

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

Resposta d’exemple

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

Obtenir les claus externes registrades a la vostra organització

Sol·licitud d’exemple

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

Resposta d’exemple

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

Validar una clau externa

Podeu fer servir aquest endpoint per comprovar diverses coses

  • Que la vostra configuració externa del núvol continua sent vàlida amb OpenAI després d’haver fet canvis (veureu una resposta correcta)

  • Que la revocació de la vostra clau s’ha fet correctament, OpenAI l’està processant i entrarà en vigor quan hagin expirat els TTL de memòria cau d’1 hora (veureu una resposta d’error)

Sol·licitud d’exemple

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

Resposta d’exemple

{
 "status": "success"
}

O bé un error retornat pel proveïdor de núvol.

endpoints de nivell de projecte

Crear un projecte nou amb un ID de clau externa

És el mateix que l’endpoint Create Project existent, amb l’afegit del paràmetre external_key_id a la sol·licitud i a la resposta.

Sol·licitud d’exemple

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

Resposta d’exemple

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

[Restringit] Actualitzar un projecte existent amb un ID de clau externa

És el mateix que l’endpoint Update Project existent, amb l’afegit del paràmetre external_key_id a la sol·licitud i a la resposta.


Recomanem crear projectes d’API nous per a les vostres càrregues de treball d’EKM. Si voleu EKM en tots els vostres projectes d’API existents, demaneu-ho al vostre director de compte i us afegirem a la marca de funcionalitat. Tingueu en compte les pràctiques recomanades següents abans de desplegar EKM als vostres projectes de producció existents.

  • Proveu primer totes les funcions d’API que feu servir en producció al vostre projecte d’API EKM de prova

  • Feu un desplegament gradual en lloc d’afegir EKM a tots els projectes d’API de producció alhora

Sol·licitud d’exemple

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

Llistar tots els projectes de la vostra organització

És el mateix que l’endpoint existent, però amb external_key_id afegit a la resposta de l’API

Sol·licitud d’exemple

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

Resposta d’exemple

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

T'ha estat útil aquest article?