Përmbledhje
Qasja
Pikat fundore të EKM-së janë të qasshme në API-në e menaxhimit përmes një çelësi API të administratorit. https://platform.openai.com/settings/organization/admin-keys (mos përdorni një çelës API të zakonshëm). Çelësat API të administratorit janë në dispozicion të pronarëve të organizatës.
Përdorni
api.external_keys.writepër të krijuar ose fshirë çelësa të jashtëm dheapi.external_keys.readpër t'i listuar, marrë ose vërtetuar ata. Një çelësi i duhen të dyja lejet vetëm nëse duhet të kryejë si veprime leximi, ashtu edhe shkrimi.
Përdorimi
Konfigurimi juaj i EKM-së regjistrohet në nivel organizate përmes një pike fundore të re: https://api.openai.com/v1/organization/external_keys.
Regjistrimi i konfigurimit tuaj të EKM-së kthen një external_key_id në formën extkey_xxxx.
Konfigurimet e EKM-së aktivizohen në nivel projekti duke dërguar një external_key_id në trupin e kërkesës te pika fundore ekzistuese për krijimin e projekteve: https://api.openai.com/v1/organization/projects.
Kufizimet
Fillimisht duhet ta provoni EKM në një projekt të ri përmes API-së së menaxhimit.
Rekomandojmë të krijoni projekte të reja për ngarkesat tuaja të punës EKM. Merrni parasysh praktikat e mëposhtme të rekomanduara përpara se të zbatoni EKM në projektet tuaja ekzistuese në prodhim.
Fillimisht, provoni në projektin tuaj testues API me EKM të gjitha veçoritë e API-së që përdorni në prodhim.
Zbatojeni EKM gradualisht, në vend që ta aktivizoni në të gjitha projektet API në prodhim njëherësh.
endpoints të nivelit të organizatës
Regjistroni një çelës të jashtëm në organizatën tuaj
AWS
Shembull kërkese:
type: string - gjithmonë “aws”
name: string - Një emër i kuptueshëm për konfigurimin tuaj
role_arn: string - ARN-ja e rolit që OpenAI do të marrë në mjedisin tuaj cloud
kms_arn: string - ARN-ja e sistemit të menaxhimit të çelësave për çelësin kryesor që menaxhoni
external_id: string - ID-ja e organizatës suaj ose ID-ja e projektit të API-së
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>"
}'Shembull përgjigjeje:
{
"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
Shembull kërkese:
type: string - gjithmonë “gcp”,
name: string - Një emër i kuptueshëm për konfigurimin tuaj
workload_identity_project_number: string - Numri identifikues i projektit GCP ku keni regjistruar identitetin e ngarkesës së punës të OpenAI
workload_identity_pool_id: string - Grupi që përmban ofruesin e Workload Identity që keni regjistruar për OpenAI
workload_identity_provider_id: string - Ofruesi i Workload Identity që keni regjistruar për OpenAI
audience: string - Audienca që OpenAI duhet të dërgojë në token kur marrim një rol përmes GCP STS tuaj
kms_project_id: string - Emri i projektit GCP ku ndodhet KMS-ja juaj
kms_key_ring_name: string - Grupi i çelësave në sistemin e menaxhimit të çelësave që përmban çelësin kryesor që menaxhoni
kms_key_name: string - Emri i çelësit kryesor të sistemit të menaxhimit të çelësave
kms_key_location: string - Rajoni ku ndodhet çelësi kryesor i sistemit tuaj të menaxhimit të çelësave
Nëse KMS-ja juaj ndodhet në një projekt GCP të ndryshëm nga ai ku keni regjistruar Workload Identity të OpenAI, sigurohuni që projekti që përmban Workload Identity të OpenAI të ketë të paktën KMS të aktivizuar, duke shkuar te 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"
}'Shembull përgjigjeje:
{
"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
Shembull kërkese:
type: string - gjithmonë “azure”,
name: string - Një emër i kuptueshëm për konfigurimin tuaj
tenant_id: string - UUID-ja e instancës suaj organizative në Azure
vault_uri: string - URI-ja e kasafortës Azure që përmban çelësin kryesor që menaxhoni
key_name: string - Emri i çelësit kryesor të Azure Key Vault që menaxhoni.
Duhet të ketë formën <org-xxx>--<any_name>
ku org-xxx është ID-ja e organizatës suaj në OpenAI, të cilën mund ta gjeni te 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"
}'Shembull përgjigjeje:
{
"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"
}OCI
Konfiguroni një çelës AES-256 të aktivizuar dhe jepini OpenAI qasje në të. Çelësi duhet të ketë një etiketë të formës së lirë openai_organization_id, me vlerë ID-në e organizatës suaj në OpenAI. Për hapat e konfigurimit, shihni: Konfigurimi i OCI Vault për menaxhimin e çelësave të ndërmarrjes.
Shembull kërkese:
type: string - gjithmonë "oci"
purpose: string - "ekm"; vlera e parazgjedhur kur nuk jepet
name: string - Një emër i kuptueshëm për konfigurimin tuaj
region: string - Rajoni OCI ku ndodhen kasaforta dhe çelësi juaj
vault_ocid: string - OCID-ja e plotë e kasafortës suaj
key_ocid: string - OCID-ja e plotë e çelësit tuaj AES-256
Mos dërgoni key_version_ocid për EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Shembull përgjigjeje:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}API-ja kthen HTTP 200 kur veprimi kryhet me sukses. Ruani vlerën id të kthyer dhe përdoreni si external_key_id kur krijoni një projekt. Veprimet ekzistuese të listimit, marrjes, vërtetimit dhe fshirjes vlejnë edhe për regjistrimet OCI.
Për rikuperimin PSP, përdorni një regjistrim të veçantë RSA-3072 me purpose: "psp_decryption" dhe një vlerë të saktë key_version_ocid. Vendosni si vlerë të psp_decryption_key_id ID-në e regjistrimit të tij në OpenAI. Për atë çelës RSA, OpenAI ka nevojë vetëm për qasje leximi te metadatat dhe çelësat publikë. Për konfigurimin e plotë, shihni: Konfiguroni çelësat asimetrikë — OCI Vault.
Fshini një çelës të jashtëm të regjistruar në organizatën tuaj
Shënim: Fshirja bllokohet për sa kohë që regjistrimi përdoret nga një projekt aktiv ose një hapësirë pune aktive. Për EKM, fillimisht arkivoni projektet API të lidhura; një regjistrim EKM i lidhur me një hapësirë pune mbetet i mbrojtur. Për rikuperimin PSP, përpara se të fshini regjistrimin, zëvendësoni ose zbrazni vlerën e psp_decryption_key_id në çdo projekt aktiv që i referohet atij. Fshirja e një regjistrimi në OpenAI nuk e fshin çelësin në renë kompjuterike.
Shembull kërkese
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Shembull përgjigjeje
{
"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>"
}Merrni çelësat e jashtëm të regjistruar në organizatën tuaj
Pa një filtër sipas qëllimit, lista përfshin si regjistrimet EKM, ashtu edhe ato për rikuperimin PSP. Përdorni ?purpose=ekm ose ?purpose=psp_decryption për të filtruar sipas qëllimit.
Shembull kërkese
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Shembull përgjigjeje
{
"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"
}Vërtetoni një çelës të jashtëm
Përdorni vërtetimin për të kontrolluar nëse OpenAI ka ende qasje në çelësin tuaj në renë kompjuterike.
Për EKM, OpenAI kontrollon nëse mund të enkriptojë dhe dekriptojë me çelësin. Për mënyrën si funksionojnë revokimi dhe ruajtja në memorien e përkohshme, shihni: udhëzimet për ciklin e jetës së çelësit.
Për rikuperimin PSP, OpenAI merr çelësin publik të versionit të regjistruar dhe e krahason me kopjen e ruajtur. Vërtetimi i suksesshëm nuk konfirmon se identiteti juaj i rikuperimit mund të dekriptojë. Vërtetimi i dështuar nuk e heq ose zëvendëson kopjen e ruajtur të çelësit publik.
Marrja e një regjistrimi me GET kthen konfigurimin e ruajtur dhe nuk e rikontrollon qasjen në çelësin tuaj në renë kompjuterike.
Shembull kërkese
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Shembull përgjigjeje
{
"status": "success"
}Ose është shfaqur një gabim nga ofruesi i cloud-it.
endpoints të nivelit të projektit
Krijoni një projekt të ri me ID-në e një çelësi të jashtëm
Kjo është e njëjta pikë fundore ekzistuese për krijimin e projekteve, me shtimin e parametrit external_key_id në kërkesë dhe në përgjigje.
Shembull kërkese
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"
}'Shembull përgjigjeje
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Përditësoni një projekt ekzistues me ID-në e një çelësi të jashtëm
Kjo është e njëjtë me pikën fundore ekzistuese për përditësimin e projektit, me shtimin e parametrit external_key_id në kërkesë dhe përgjigje.
Rekomandojmë të krijoni projekte të reja API për ngarkesat tuaja të punës EKM. Merrni parasysh praktikat e mëposhtme të rekomanduara përpara se të zbatoni EKM në projektet tuaja ekzistuese në prodhim.
Fillimisht, provoni në projektin tuaj testues API me EKM të gjitha veçoritë e API-së që përdorni në prodhim.
Zbatojeni EKM gradualisht, në vend që ta aktivizoni në të gjitha projektet API në prodhim njëherësh.
Shembull kërkese
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"
}'Listoni të gjitha projektet në organizatën tuaj
Kjo është e njëjta pikë fundore si ajo ekzistuese, por me shtimin e external_key_id në përgjigjen e API-së.
Shembull kërkese
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Shembull përgjigjeje
{
"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
}