Σύνοψη
Πρόσβαση
Τα τελικά σημεία EKM είναι προσβάσιμα στο API διαχείρισης μέσω ενός κλειδιού API διαχειριστή. https://platform.openai.com/settings/organization/admin-keys (μη χρησιμοποιήσετε κανονικό κλειδί API). Τα κλειδιά API διαχειριστή είναι διαθέσιμα στους κατόχους οργανισμών.
Χρησιμοποιήστε το
api.external_keys.writeγια να δημιουργήσετε ή να διαγράψετε εξωτερικά κλειδιά και τοapi.external_keys.readγια να παραθέσετε ή να επικυρώσετε εξωτερικά κλειδιά. Ένα κλειδί χρειάζεται και τα δύο πεδία δικαιωμάτων μόνο εάν πρέπει να εκτελεί λειτουργίες τόσο ανάγνωσης όσο και εγγραφής.Προς το παρόν, πρέπει να ενεργοποιήσουμε μια σημαία λειτουργίας για να αποκτήσει ο οργανισμός σας πρόσβαση σε αυτά τα τελικά σημεία. Η σημαία λειτουργίας είναι ενεργοποιημένη αν δείτε ότι το υπάρχον τελικό σημείο παράθεσης έργων επιστρέφει το external_key_id: https://api.openai.com/v1/organization/projects.
Χρήση
Η διαμόρφωση 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 σε υπάρχον έργο, μπορούμε να ενεργοποιήσουμε τη σχετική σημαία λειτουργίας για εσάς. Λάβετε υπόψη τις παρακάτω βέλτιστες πρακτικές πριν ενεργοποιήσετε το 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"
}Διαγραφή εξωτερικού κλειδιού που έχει καταχωριστεί στον οργανισμό σας
Σημείωση: Μπορείτε να διαγράψετε ένα εξωτερικό κλειδί μόνο αν δεν είναι συσχετισμένο με κανένα ενεργό έργο API ή χώρο εργασίας. Αν είναι συσχετισμένο με ενεργό έργο API, αρχειοθετήστε πρώτα το έργο. Αν είναι συσχετισμένο με χώρο εργασίας, το κλειδί δεν μπορεί να διαγραφεί.
Παράδειγμα αιτήματος
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>"
}Ανάκτηση των εξωτερικών κλειδιών που έχουν καταχωριστεί στον οργανισμό σας
Παράδειγμα αιτήματος
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"
}Επικύρωση εξωτερικού κλειδιού
Μπορείτε να χρησιμοποιήσετε αυτό το τελικό σημείο για να ελέγξετε τα εξής:
Ότι η διαμόρφωση του εξωτερικού περιβάλλοντος cloud σας παραμένει έγκυρη για χρήση με την OpenAI μετά τις αλλαγές που κάνατε (θα λάβετε απόκριση επιτυχίας).
Ότι η ανάκληση του κλειδιού σας έχει γίνει σωστά, υποβάλλεται σε επεξεργασία από την OpenAI και θα τεθεί σε ισχύ μόλις λήξουν οι χρόνοι διατήρησης (TTL) της μίας ώρας στην προσωρινή μνήμη (θα λάβετε απόκριση σφάλματος).
Παράδειγμα αιτήματος
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 σας, ζητήστε το από τον υπεύθυνο του λογαριασμού σας και θα ενεργοποιήσουμε τη σχετική σημαία λειτουργίας για εσάς. Λάβετε υπόψη τις παρακάτω βέλτιστες πρακτικές πριν ενεργοποιήσετε το 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
}