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

EKM (claus externes) a la Management API

Aprèn a gestionar les claus externes d'EKM amb l'API de gestió.

Actualització: yesterday

Resum

Accés

  • Pots accedir als punts finals d'EKM a l'API de gestió amb una clau d'API d'administració. https://platform.openai.com/settings/organization/admin-keys (no facis servir una clau d'API normal). Les claus d'API d'administració estan disponibles per als propietaris de l'organització.

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

  • Actualment, hem d'habilitar l'accés de la teva organització a aquests punts finals mitjançant un indicador de funcionalitat. Sabràs que tens l'indicador de funcionalitat activat si el punt final existent per llistar projectes retorna external_key_id: https://api.openai.com/v1/organization/projects.

Ús

Restriccions

  • Primer has de provar EKM en un projecte nou mitjançant l'API de gestió.

  • Recomanem crear projectes nous per a les teves càrregues de treball amb EKM. Tanmateix, si vols EKM en un projecte existent, et podem activar l'indicador de funcionalitat. Tingues en compte les bones pràctiques següents abans de desplegar EKM als teus projectes de producció existents.

    • Prova primer totes les funcions de l'API que fas servir en producció al teu projecte d'API de prova amb EKM.

    • Fes un desplegament gradual en lloc d'activar EKM a tots els projectes d'API de producció alhora.

endpoints de nivell d’organització

Registrar una clau externa a la vostra organització

AWS

Exemple de sol·licitud:

  • type: cadena - sempre "aws"

  • name: cadena - Un nom descriptiu per a la teva configuració

  • role_arn: cadena - L'ARN del rol que OpenAI assumirà al teu núvol

  • kms_arn: cadena - L'ARN del sistema de gestió de claus corresponent a la clau mestra que gestiones

  • external_id: cadena - El teu ID d'organització o de 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>"
}'

Exemple de resposta:

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

Exemple de sol·licitud:

  • type: cadena - sempre "gcp",

  • name: cadena - Un nom descriptiu per a la teva configuració

  • workload_identity_project_number: cadena - El número del projecte de GCP on has registrat la identitat de càrrega de treball d'OpenAI

  • workload_identity_pool_id: cadena - El grup que conté el proveïdor de Workload Identity que has registrat per a OpenAI

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

  • audience: cadena - L'audiència que OpenAI ha de passar al testimoni quan assumim un rol mitjançant el teu STS de GCP

  • kms_project_id: cadena - El nom del projecte de GCP on es troba el teu KMS

  • kms_key_ring_name: cadena - L'anell de claus del sistema de gestió de claus que conté la clau mestra que gestiones

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

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

Si el teu KMS es troba en un projecte de GCP diferent d'aquell on has registrat la identitat de Workload Identity d'OpenAI, assegura't que el projecte que conté aquesta identitat tingui, com a mínim, KMS habilitat. Pots comprovar-ho 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"
}'

Exemple de resposta:

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

Exemple de sol·licitud:

  • type: cadena - sempre "azure",

  • name: cadena - Un nom descriptiu per a la teva configuració

  • tenant_id: cadena - L'UUID del teu inquilí d'Azure

  • vault_uri: cadena - L'URI del magatzem d'Azure que conté la clau mestra que gestiones

  • key_name: cadena - El nom de la clau mestra d'Azure Key Vault que gestiones.

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

Exemple de resposta:

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

Suprimeix una clau externa registrada a la teva organització

Nota: Només pots 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, primer arxiva el projecte. Si està associada a un espai de treball, no es pot suprimir.

Exemple de sol·licitud

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

Exemple de resposta

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

Obtén les claus externes registrades a la teva organització

Exemple de sol·licitud

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

Exemple de resposta

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

Valida una clau externa

Pots fer servir aquest punt final per comprovar diversos aspectes:

  • Que la configuració del teu núvol extern continua sent vàlida per a OpenAI després de fer-hi canvis (veuràs una resposta de confirmació).

  • Que la revocació de la clau s'ha fet correctament, que OpenAI l'està processant i que tindrà efecte un cop hagin caducat els TTL d'una hora de la memòria cau (veuràs una resposta d'error).

Exemple de sol·licitud

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

Exemple de resposta

{
  "status": "success"
}

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

endpoints de nivell de projecte

Crea un projecte nou amb un ID de clau externa

És el mateix punt final que ja existeix per crear projectes, però amb el paràmetre external_key_id afegit a la sol·licitud i a la resposta.

Exemple de sol·licitud

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

Exemple de resposta

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

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

És el mateix punt final que ja existeix per actualitzar projectes, però amb el paràmetre external_key_id afegit a la sol·licitud i a la resposta.

Recomanem crear projectes d'API nous per a les teves càrregues de treball amb EKM. Si vols EKM a tots els teus projectes d'API existents, demana-ho al teu responsable de compte i t'activarem l'indicador de funcionalitat. Tingues en compte les bones pràctiques següents abans de desplegar EKM als teus projectes de producció existents.

  • Prova primer totes les funcions de l'API que fas servir en producció al teu projecte d'API de prova amb EKM.

  • Fes un desplegament gradual en lloc d'activar EKM a tots els projectes d'API de producció alhora.

Exemple de sol·licitud

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

Llista tots els projectes de la teva organització

És el mateix punt final que ja existeix, però amb external_key_id afegit a la resposta de l'API.

Exemple de sol·licitud

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

Exemple de resposta

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