Σύνοψη

Πρόσβαση

• Τα τελικά σημεία EKM είναι προσβάσιμα στο Management API μέσω ενός Admin API Key. https://platform.openai.com/settings/organization/admin-keys (μη χρησιμοποιείτε κανονικό API key). Τα Admin API keys είναι διαθέσιμα στους ιδιοκτήτες οργανισμού.

• Χρησιμοποιήστε το api.external_keys.write για να δημιουργήσετε ή να διαγράψετε εξωτερικά κλειδιά και το api.external_keys.read για να εμφανίσετε ή να επικυρώσετε εξωτερικά κλειδιά. Ένα μόνο κλειδί χρειάζεται και τα δύο scopes μόνο αν πρέπει να εκτελεί τόσο λειτουργίες ανάγνωσης όσο και εγγραφής.

• Αυτή τη στιγμή πρέπει να ενεργοποιήσουμε τη feature flag για τον οργανισμό σας σε αυτά τα τελικά σημεία. Ξέρετε ότι έχετε τη feature flag αν βλέπετε να επιστρέφεται το **external_key_id ** από το υπάρχον τελικό σημείο List Projects: 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 στο body του υπάρχοντος τελικού σημείου Create Project https://api.openai.com/v1/organization/projects

Περιορισμοί

• Πρέπει πρώτα να δοκιμάσετε το EKM σε νέο έργο μέσω του Management API.

• Συνιστούμε να δημιουργείτε νέα έργα για τα φορτία εργασίας EKM σας. Ωστόσο, αν θέλετε EKM σε υπάρχον έργο, μπορούμε να σας προσθέσουμε στη feature flag. Λάβετε υπόψη τις ακόλουθες βέλτιστες πρακτικές πριν αναπτύξετε το EKM στα υπάρχοντα έργα παραγωγής σας.

  • Δοκιμάστε πρώτα στο δοκιμαστικό EKM API project σας όλες τις δυνατότητες API που χρησιμοποιείτε στην παραγωγή

  • Εφαρμόστε σταδιακή κυκλοφορία αντί να συμπληρώσετε το EKM σε όλα τα production API projects ταυτόχρονα

Τελικά σημεία επιπέδου οργανισμού

Καταχωρίστε ένα εξωτερικό κλειδί στον οργανισμό σας

AWS

Δείγμα αιτήματος

• type: string - πάντα «aws»

• name: string - Ένα φιλικό όνομα για τη ρύθμισή σας

• role_arn: string - Το Role ARN που θα αναλάβει το OpenAI στο cloud σας

• kms_arn: string - Το ARN του Key Management System για το κύριο κλειδί που διαχειρίζεστε

• external_id: string - Το organization id ή το API project id σας

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: string - πάντα "gcp",

• name: string - Ένα φιλικό όνομα για τη ρύθμισή σας

• workload_identity_project_number: string - Ο 12ψήφιος αριθμός έργου GCP όπου καταχωρίσατε το workload identity του OpenAI

• workload_identity_pool_id: string - Το pool που περιέχει τον πάροχο Workload Identity που καταχωρίσατε για το OpenAI

• workload_identity_provider_id: string - Ο πάροχος Workload Identity που καταχωρίσατε για το OpenAI

• audience: string - Το audience που πρέπει να περάσει το OpenAI στο token όταν αναλαμβάνουμε ρόλο μέσω του GCP STS σας

• kms_project_id: string - Το όνομα του έργου GCP όπου βρίσκεται το KMS σας

• kms_key_ring_name: string - Το key ring του Key Management System που περιέχει το κύριο κλειδί που διαχειρίζεστε

• kms_key_name: string - Το όνομα του κύριου κλειδιού του Key Management System

• kms_key_location: string - Η περιοχή όπου βρίσκεται το κύριο κλειδί του Key Management System

Αν το 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: string - πάντα "azure",

• name: string - Ένα φιλικό όνομα για τη ρύθμισή σας

• tenant_id: string - Το UUID tenant του Azure σας

• vault_uri: string - Το URI του Azure vault που περιέχει το κύριο κλειδί που διαχειρίζεστε

• key_name: string - Το όνομα του κύριου κλειδιού Azure Key Vault που διαχειρίζεστε.

  • Πρέπει να έχει τη μορφή <org-xxx>--<any_name>

  • όπου το org-xxx είναι το OpenAI organization ID σας, το οποίο μπορείτε να βρείτε στη διεύθυνση 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"
}

Διαγράψτε ένα εξωτερικό κλειδί που έχει καταχωριστεί στον οργανισμό σας

Σημείωση: Μπορείτε να διαγράψετε ένα εξωτερικό κλειδί μόνο αν δεν σχετίζεται με ενεργά έργα. Αν σχετίζεται με ενεργό έργο, πρέπει πρώτα να αρχειοθετήσετε αυτό το έργο.

Δείγμα αιτήματος

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 και θα τεθεί σε ισχύ αφού λήξουν τα cache TTLs της 1 ώρας (θα δείτε απόκριση σφάλματος)

Δείγμα αιτήματος

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

Δείγμα απόκρισης

{
 "status": "success"
}

Ή ένα σφάλμα που προήλθε από τον πάροχο cloud.

Τελικά σημεία επιπέδου έργου

Δημιουργήστε νέο έργο με external key ID

Αυτό είναι ίδιο με το υπάρχον τελικό σημείο Create Project, με την προσθήκη της παραμέτρου external_key_id στο αίτημα και στην απόκριση.

Δείγμα αιτήματος

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
   "name": "Κάποιο έργο",
   "external_key_id": "extkey_xxxx"
}'

Δείγμα απόκρισης

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Κάποιο έργο",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[Περιορισμένο] Ενημερώστε υπάρχον έργο με external key ID

Αυτό είναι ίδιο με το υπάρχον τελικό σημείο Update Project, με την προσθήκη της παραμέτρου external_key_id στο αίτημα και στην απόκριση.

Συνιστούμε να δημιουργείτε νέα API projects για τα φορτία εργασίας EKM σας. Αν θέλετε EKM σε όλα τα υπάρχοντα API projects σας, ζητήστε το από τον account director σας και θα σας προσθέσουμε στη feature flag. Λάβετε υπόψη τις ακόλουθες βέλτιστες πρακτικές πριν αναπτύξετε το EKM στα υπάρχοντα έργα παραγωγής σας.

• Δοκιμάστε πρώτα στο δοκιμαστικό EKM API project σας όλες τις δυνατότητες API που χρησιμοποιείτε στην παραγωγή

• Εφαρμόστε σταδιακή κυκλοφορία αντί να συμπληρώσετε το EKM σε όλα τα production API projects ταυτόχρονα

Δείγμα αιτήματος

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": "Όνομα έργου",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}