Sommarju
Aċċess
Il-punti ta' tmiem tal-EKM huma aċċessibbli fl-API tal-Ġestjoni permezz ta' ċavetta tal-API tal-amministratur. https://platform.openai.com/settings/organization/admin-keys (tużax ċavetta tal-API normali). Iċ-ċwievet tal-API tal-amministratur huma disponibbli għas-sidien tal-organizzazzjoni.
Uża
api.external_keys.writebiex toħloq jew tħassar ċwievet esterni, uapi.external_keys.readbiex telenka jew tivvalida ċwievet esterni. Ċavetta waħda teħtieġ iż-żewġ ambiti ta' permess biss jekk trid twettaq operazzjonijiet kemm ta' qari kif ukoll ta' kitba.Bħalissa rridu nattivaw l-aċċess tal-organizzazzjoni tiegħek għal dawn il-punti ta' tmiem permezz ta' feature flag. Tista' tkun taf li l-feature flag hija attivata jekk tara external_key_id fit-tweġiba mill-punt ta' tmiem eżistenti għall-elenkar tal-proġetti: https://api.openai.com/v1/organization/projects.
Użu
Il-konfigurazzjoni tal-EKM tiegħek tiġi rreġistrata fil-livell tal-organizzazzjoni permezz ta' punt ta' tmiem ġdid https://api.openai.com/v1/organization/external_keys.
Meta tirreġistra l-konfigurazzjoni tal-EKM tiegħek, tirċievi external_key_id fil-forma extkey_xxxx.
Il-konfigurazzjonijiet tal-EKM jiġu attivati fil-livell tal-proġett billi tinkludi external_key_id fil-korp tat-talba lill-punt ta' tmiem eżistenti għall-ħolqien ta' proġett https://api.openai.com/v1/organization/projects.
Restrizzjonijiet
L-ewwel trid tittestja l-EKM fuq proġett ġdid permezz tal-API tal-Ġestjoni.
Nirrakkomandaw li toħloq proġetti ġodda għall-kompiti li twettaq bl-EKM. Madankollu, jekk trid l-EKM fuq proġett eżistenti, nistgħu nattivawlek il-feature flag. Qis l-aħjar prattiki li ġejjin qabel ma tintroduċi l-EKM fil-proġetti eżistenti tiegħek fl-ambjent ta' produzzjoni.
L-ewwel ittestja l-funzjonalitajiet kollha tal-API li tuża fl-ambjent ta' produzzjoni fil-proġett tat-test tiegħek tal-API bl-EKM.
Introduċi l-EKM gradwalment minflok tattivah fuq il-proġetti kollha tal-API fl-ambjent ta' produzzjoni f'daqqa.
endpoints fil-livell tal-organizzazzjoni
Irreġistra ċavetta esterna fl-organizzazzjoni tiegħek
AWS
Eżempju ta' talba:
type: string - dejjem “aws”
name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek
role_arn: string - L-ARN tar-rwol li OpenAI se tassumi fil-cloud tiegħek
kms_arn: string - L-ARN tas-Sistema tal-Ġestjoni taċ-Ċwievet għaċ-ċavetta prinċipali li timmaniġġja
external_id: string - L-ID tal-Organizzazzjoni tiegħek jew l-ID tal-proġett tal-API tiegħek
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>"
}'Eżempju ta' tweġiba:
{
"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
Eżempju ta' talba:
type: string - dejjem “gcp”,
name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek
workload_identity_project_number: string - In-numru tal-proġett tal-GCP fejn irreġistrajt l-identità tal-kompiti ta' OpenAI
workload_identity_pool_id: string - Il-grupp li fih il-fornitur ta' Workload Identity li rreġistrajt għal OpenAI
workload_identity_provider_id: string - Il-fornitur ta' Workload Identity li rreġistrajt għal OpenAI
audience: string - L-udjenza li OpenAI għandha tinkludi fit-token meta nassumu rwol permezz tal-GCP STS tiegħek
kms_project_id: string - L-isem tal-proġett tal-GCP li fih il-KMS tiegħek
kms_key_ring_name: string - Il-grupp ta' ċwievet tas-Sistema tal-Ġestjoni taċ-Ċwievet li fih iċ-ċavetta prinċipali li timmaniġġja
kms_key_name: string - L-isem taċ-ċavetta prinċipali tas-Sistema tal-Ġestjoni taċ-Ċwievet
kms_key_location: string - Ir-reġjun fejn tinsab iċ-ċavetta prinċipali tas-Sistema tal-Ġestjoni taċ-Ċwievet tiegħek
Jekk il-KMS tiegħek jinsab fi proġett tal-GCP differenti minn dak fejn irreġistrajt il-Workload Identity ta' OpenAI, kun żgur li l-proġett li fih il-Workload Identity ta' OpenAI għandu tal-inqas il-KMS attivat billi tmur fuq 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"
}'Eżempju ta' tweġiba:
{
"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
Eżempju ta' talba:
type: string - dejjem “azure”,
name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek
tenant_id: string - L-UUID tat-tenant tiegħek ta' Azure
vault_uri: string - L-URI tal-kaxxa-forti ta' Azure li fiha ċ-ċavetta prinċipali li timmaniġġja
key_name: string - L-isem taċ-ċavetta prinċipali ta' Azure Key Vault li timmaniġġja.
Irid ikollu l-forma <org-xxx>--<any_name>
fejn org-xxx huwa l-ID tal-Organizzazzjoni tiegħek ta' OpenAI, li tista' ssib fuq https://platform.openai.com/settings/organization/general
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"
}'Eżempju ta' tweġiba:
{
"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"
}Ħassar ċavetta esterna rreġistrata mal-organizzazzjoni tiegħek
Nota: Tista' tħassar ċavetta esterna biss jekk ma tkun assoċjata ma' ebda proġett attiv tal-API jew workspace. Jekk tkun assoċjata ma' proġett attiv tal-API, l-ewwel arkivja dak il-proġett. Jekk tkun assoċjata ma' workspace, iċ-ċavetta ma tistax titħassar.
Eżempju ta' talba
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Eżempju ta' tweġiba
{
"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>"
}Ikseb iċ-ċwievet esterni rreġistrati mal-organizzazzjoni tiegħek
Eżempju ta' talba
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Eżempju ta' tweġiba
{
"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"
}Ivvalida ċavetta esterna
Tista' tuża dan il-punt ta' tmiem biex tiċċekkja diversi affarijiet:
Li l-konfigurazzjoni tal-cloud estern tiegħek tibqa' valida ma' OpenAI wara li tkun għamilt bidliet (tara tweġiba li tindika suċċess).
Li r-revoka taċ-ċavetta tiegħek saret sew, qed tiġi pproċessata minn OpenAI, u se tidħol fis-seħħ wara li jiskadu t-TTLs ta' siegħa tal-cache (tara tweġiba li tindika żball).
Eżempju ta' talba
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Eżempju ta' tweġiba
{
"status": "success"
}Jew, żball muri mill-fornitur tal-cloud.
endpoints fil-livell tal-proġett
Oħloq proġett ġdid b'ID ta' ċavetta esterna
Dan huwa l-istess bħall-punt ta' tmiem eżistenti għall-ħolqien ta' proġett, biż-żieda tal-parametru external_key_id fit-talba u fit-tweġiba.
Eżempju ta' talba
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"
}'Eżempju ta' tweġiba
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[Ristrett] Aġġorna proġett eżistenti b'ID ta' ċavetta esterna
Dan huwa l-istess bħall-punt ta' tmiem eżistenti għall-aġġornament ta' proġett, biż-żieda tal-parametru external_key_id fit-talba u fit-tweġiba.
Nirrakkomandaw li toħloq proġetti ġodda tal-API għall-kompiti li twettaq bl-EKM. Jekk trid l-EKM fuq il-proġetti eżistenti kollha tal-API tiegħek, staqsi lid-direttur tal-kont tiegħek u nattivawlek il-feature flag. Qis l-aħjar prattiki li ġejjin qabel ma tintroduċi l-EKM fil-proġetti eżistenti tiegħek fl-ambjent ta' produzzjoni.
L-ewwel ittestja l-funzjonalitajiet kollha tal-API li tuża fl-ambjent ta' produzzjoni fil-proġett tat-test tiegħek tal-API bl-EKM.
Introduċi l-EKM gradwalment minflok tattivah fuq il-proġetti kollha tal-API fl-ambjent ta' produzzjoni f'daqqa.
Eżempju ta' talba
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"
}'Elenka l-proġetti kollha tal-organizzazzjoni tiegħek
Dan huwa l-istess bħall-punt ta' tmiem eżistenti, iżda biż-żieda ta' external_key_id fit-tweġiba tal-API.
Eżempju ta' talba
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Eżempju ta' tweġiba
{
"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
}