Σύνοψη
Πρόσβαση
Τα τελικά σημεία EKM είναι προσβάσιμα στο API διαχείρισης με ένα κλειδί API διαχειριστή. https://platform.openai.com/settings/organization/admin-keys (μη χρησιμοποιείτε ένα συνηθισμένο κλειδί API). Τα κλειδιά API διαχειριστή είναι διαθέσιμα στους κατόχους οργανισμών.
Χρησιμοποιήστε το
api.external_keys.writeγια τη δημιουργία ή τη διαγραφή εξωτερικών κλειδιών και τοapi.external_keys.readγια την προβολή λίστας, την ανάκτηση ή την επικύρωση εξωτερικών κλειδιών. Ένα κλειδί χρειάζεται και τα δύο πεδία δικαιωμάτων μόνο αν πρέπει να εκτελεί λειτουργίες τόσο ανάγνωσης όσο και εγγραφής.
Χρήση
Η διαμόρφωση EKM σας καταχωρίζεται σε επίπεδο οργανισμού μέσω ενός νέου τελικού σημείου: https://api.openai.com/v1/organization/external_keys.
Η καταχώριση της διαμόρφωσης EKM σας επιστρέφει ένα external_key_id της μορφής extkey_xxxx.
Οι διαμορφώσεις EKM ενεργοποιούνται σε επίπεδο έργου, με τη διαβίβαση ενός external_key_id στο σώμα του αιτήματος προς το υπάρχον τελικό σημείο δημιουργίας έργου https://api.openai.com/v1/organization/projects.
Περιορισμοί
Πρέπει πρώτα να δοκιμάσετε το EKM σε ένα νέο έργο μέσω του API διαχείρισης.
Συνιστούμε να δημιουργήσετε νέα έργα για τους φόρτους εργασίας EKM. Λάβετε υπόψη τις ακόλουθες βέλτιστες πρακτικές πριν εφαρμόσετε το EKM στα υπάρχοντα έργα σας που βρίσκονται σε παραγωγική λειτουργία.
Δοκιμάστε πρώτα όλες τις δυνατότητες API που χρησιμοποιείτε στο περιβάλλον παραγωγής στο δοκιμαστικό έργο API με EKM.
Εφαρμόστε το EKM σταδιακά και όχι ταυτόχρονα σε όλα τα έργα API που βρίσκονται σε παραγωγική λειτουργία.
Endpoints σε επίπεδο οργανισμού
Καταχώριση εξωτερικού κλειδιού στον οργανισμό σας
AWS
Παράδειγμα αιτήματος:
type: συμβολοσειρά - πάντα «aws»
name: συμβολοσειρά - Ένα εύκολα αναγνωρίσιμο όνομα για τη διαμόρφωσή σας
role_arn: συμβολοσειρά - Το ARN του ρόλου που θα αναλάβει η OpenAI στο περιβάλλον cloud σας
kms_arn: συμβολοσειρά - Το ARN του συστήματος διαχείρισης κλειδιών για το κύριο κλειδί που διαχειρίζεστε
external_id: συμβολοσειρά - Το αναγνωριστικό οργανισμού ή έργου 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>"
}'Παράδειγμα απόκρισης:
{
"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
Παράδειγμα αιτήματος:
type: συμβολοσειρά - πάντα «gcp»,
name: συμβολοσειρά - Ένα εύκολα αναγνωρίσιμο όνομα για τη διαμόρφωσή σας
workload_identity_project_number: συμβολοσειρά - Ο αριθμός του έργου GCP στο οποίο καταχωρίσατε την ταυτότητα φόρτου εργασίας της OpenAI
workload_identity_pool_id: συμβολοσειρά - Η ομάδα που περιέχει τον πάροχο Workload Identity που καταχωρίσατε για την OpenAI
workload_identity_provider_id: συμβολοσειρά - Ο πάροχος Workload Identity που καταχωρίσατε για την OpenAI
audience: συμβολοσειρά - Ο αποδέκτης που πρέπει να διαβιβάζει η OpenAI στο διακριτικό κατά την ανάληψη ρόλου μέσω του GCP STS σας
kms_project_id: συμβολοσειρά - Το όνομα του έργου GCP στο οποίο βρίσκεται το KMS σας
kms_key_ring_name: συμβολοσειρά - Η κλειδοθήκη του συστήματος διαχείρισης κλειδιών που περιέχει το κύριο κλειδί που διαχειρίζεστε
kms_key_name: συμβολοσειρά - Το όνομα του κύριου κλειδιού του συστήματος διαχείρισης κλειδιών
kms_key_location: συμβολοσειρά - Η περιοχή στην οποία βρίσκεται το κύριο κλειδί του συστήματος διαχείρισης κλειδιών σας
Αν το KMS σας βρίσκεται σε διαφορετικό έργο GCP από εκείνο στο οποίο καταχωρίσατε το Workload Identity της OpenAI, βεβαιωθείτε ότι το έργο που περιέχει το Workload Identity της OpenAI έχει τουλάχιστον ενεργοποιημένο το KMS, μεταβαίνοντας στη διεύθυνση 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"
}'Παράδειγμα απόκρισης:
{
"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
Παράδειγμα αιτήματος:
type: συμβολοσειρά - πάντα «azure»,
name: συμβολοσειρά - Ένα εύκολα αναγνωρίσιμο όνομα για τη διαμόρφωσή σας
tenant_id: συμβολοσειρά - Το UUID του μισθωτή σας στο Azure
vault_uri: συμβολοσειρά - Το URI του θησαυροφυλακίου Azure που περιέχει το κύριο κλειδί που διαχειρίζεστε
key_name: συμβολοσειρά - Το όνομα του κύριου κλειδιού Azure Key Vault που διαχειρίζεστε.
Πρέπει να έχει τη μορφή <org-xxx>--<any_name>
όπου org-xxx είναι το αναγνωριστικό οργανισμού σας στην OpenAI, το οποίο μπορείτε να βρείτε στη διεύθυνση 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"
}'Παράδειγμα απόκρισης:
{
"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
Ρυθμίστε ένα ενεργοποιημένο κλειδί AES-256 και παραχωρήστε πρόσβαση στην OpenAI. Το κλειδί πρέπει να έχει μια ετικέτα ελεύθερης μορφής openai_organization_id με τιμή το αναγνωριστικό του οργανισμού σας στην OpenAI. Για τα βήματα ρύθμισης, ανατρέξτε στο άρθρο: Ρύθμιση του OCI Vault για τη διαχείριση εταιρικών κλειδιών.
Παράδειγμα αιτήματος:
type: συμβολοσειρά - πάντα "oci"
purpose: συμβολοσειρά - "ekm"· η προεπιλεγμένη τιμή όταν παραλείπεται
name: συμβολοσειρά - Ένα εύχρηστο όνομα για τη διαμόρφωσή σας
region: συμβολοσειρά - Η περιοχή OCI που περιέχει το vault και το κλειδί σας
vault_ocid: συμβολοσειρά - Το πλήρες OCID του vault σας
key_ocid: συμβολοσειρά - Το πλήρες OCID του κλειδιού σας AES-256
Μη διαβιβάζετε το key_version_ocid για το 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>"
}'Παράδειγμα απόκρισης:
{
"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 επιστρέφει HTTP 200 σε περίπτωση επιτυχίας. Αποθηκεύστε το id που επιστρέφεται και χρησιμοποιήστε το ως external_key_id κατά τη δημιουργία ενός έργου. Οι υπάρχουσες λειτουργίες προβολής λίστας, ανάκτησης, επικύρωσης και διαγραφής ισχύουν και για τις καταχωρίσεις OCI.
Για την ανάκτηση PSP, χρησιμοποιήστε ξεχωριστή καταχώριση RSA-3072 με purpose: "psp_decryption" και την ακριβή τιμή key_version_ocid. Ορίστε το psp_decryption_key_id στο αναγνωριστικό της καταχώρισης στην OpenAI. Η OpenAI χρειάζεται μόνο πρόσβαση ανάγνωσης στα μεταδεδομένα και στα δημόσια κλειδιά για το συγκεκριμένο κλειδί RSA. Για την πλήρη διαδικασία ρύθμισης, ανατρέξτε στο άρθρο: Ρύθμιση ασύμμετρων κλειδιών — OCI Vault.
Διαγραφή εξωτερικού κλειδιού που έχει καταχωριστεί στον οργανισμό σας
Σημείωση: Η διαγραφή δεν επιτρέπεται όσο ένα ενεργό έργο ή ένας ενεργός χώρος εργασίας χρησιμοποιεί την καταχώριση. Για το EKM, αρχειοθετήστε πρώτα τα συσχετισμένα έργα API· μια καταχώριση EKM που σχετίζεται με χώρο εργασίας παραμένει προστατευμένη. Για την ανάκτηση PSP, πριν διαγράψετε την καταχώριση, αντικαταστήστε ή εκκαθαρίστε την τιμή psp_decryption_key_id σε κάθε ενεργό έργο που αναφέρεται σε αυτήν. Η διαγραφή μιας καταχώρισης στην OpenAI δεν διαγράφει το κλειδί στο cloud.
Παράδειγμα αιτήματος
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Παράδειγμα απόκρισης
{
"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>"
}Ανάκτηση των εξωτερικών κλειδιών που έχουν καταχωριστεί στον οργανισμό σας
Χωρίς φίλτρο σκοπού, η λίστα περιλαμβάνει καταχωρίσεις τόσο για EKM όσο και για ανάκτηση PSP. Χρησιμοποιήστε ?purpose=ekm ή ?purpose=psp_decryption για φιλτράρισμα βάσει σκοπού.
Παράδειγμα αιτήματος
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Παράδειγμα απόκρισης
{
"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"
}Επικύρωση εξωτερικού κλειδιού
Χρησιμοποιήστε την επικύρωση για να ελέγξετε ότι η OpenAI εξακολουθεί να έχει πρόσβαση στο κλειδί σας στο cloud.
Για το EKM, η OpenAI ελέγχει ότι μπορεί να κρυπτογραφεί και να αποκρυπτογραφεί με το κλειδί. Για τη συμπεριφορά ανάκλησης και προσωρινής αποθήκευσης, ανατρέξτε στις οδηγίες για τον κύκλο ζωής των κλειδιών.
Για την ανάκτηση PSP, η OpenAI ανακτά το δημόσιο κλειδί της καταχωρισμένης έκδοσης και το συγκρίνει με το αποθηκευμένο στιγμιότυπο. Η επιτυχής επικύρωση δεν επιβεβαιώνει ότι η ταυτότητα ανάκτησής σας μπορεί να εκτελέσει αποκρυπτογράφηση. Η αποτυχημένη επικύρωση δεν καταργεί ούτε αντικαθιστά το αποθηκευμένο στιγμιότυπο του δημόσιου κλειδιού.
Η ανάκτηση μιας καταχώρισης με GET επιστρέφει την αποθηκευμένη διαμόρφωση και δεν ελέγχει ξανά την πρόσβαση στο κλειδί σας στο cloud.
Παράδειγμα αιτήματος
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Παράδειγμα απόκρισης
{
"status": "success"
}Ή ένα σφάλμα που εμφανίστηκε από τον πάροχο cloud.
Endpoints σε επίπεδο έργου
Δημιουργία νέου έργου με αναγνωριστικό εξωτερικού κλειδιού
Πρόκειται για το ίδιο υπάρχον τελικό σημείο δημιουργίας έργου, με την προσθήκη της παραμέτρου external_key_id στο αίτημα και στην απόκριση.
Παράδειγμα αιτήματος
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"
}'Παράδειγμα απόκρισης
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Ενημέρωση υπάρχοντος έργου με αναγνωριστικό εξωτερικού κλειδιού
Πρόκειται για το ίδιο τελικό σημείο με το υπάρχον τελικό σημείο ενημέρωσης έργου, με την προσθήκη της παραμέτρου external_key_id στο αίτημα και στην απόκριση.
Συνιστούμε να δημιουργήσετε νέα έργα API για τους φόρτους εργασίας EKM. Λάβετε υπόψη τις ακόλουθες βέλτιστες πρακτικές πριν εφαρμόσετε το EKM στα υπάρχοντα έργα σας που βρίσκονται σε παραγωγική λειτουργία.
Δοκιμάστε πρώτα όλες τις δυνατότητες API που χρησιμοποιείτε στο περιβάλλον παραγωγής στο δοκιμαστικό έργο API με EKM.
Εφαρμόστε το EKM σταδιακά και όχι ταυτόχρονα σε όλα τα έργα API που βρίσκονται σε παραγωγική λειτουργία.
Παράδειγμα αιτήματος
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"
}'Παράθεση όλων των έργων του οργανισμού σας
Πρόκειται για το ίδιο υπάρχον τελικό σημείο, με την προσθήκη του external_key_id στην απόκριση του API.
Παράδειγμα αιτήματος
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Παράδειγμα απόκρισης
{
"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
}