Καταγραφή και τροποποίηση των κλειδιών σας
Σε αυτήν τη σελίδα
Καταγραφή των κλειδιών API σας
Με την πάροδο του χρόνου, η ομάδα σας συσσωρεύει κλειδιά API για διαφορετικά περιβάλλοντα, έργα και μέλη της ομάδας. Το Management API σάς επιτρέπει νααπαριθμείτε όλα τα ενεργά κλειδιά, να τα φιλτράρετε βάσει δικαιωμάτων και να τροποποιείτε τις ρυθμίσεις τους χωρίς να χρειάζεται να τα δημιουργήσετε εκ νέου.
Καταγραφή κλειδιών
Αυτό το endpoint αποτελεί το σημείο εκκίνησης για κάθε έλεγχο πρόσβασης και συχνά είναι εκεί που ανακαλύπτετε την πραγματική απογραφή: κλειδιά που δημιουργήθηκαν για μια δοκιμή πριν από οκτώ μήνες, ένα κλειδί στο όνομα πρώην μέλους της ομάδας, δύο κλειδιά παραγωγής χωρίς κανείς να γνωρίζει ποιο χρησιμοποιείται. Κάντε καταγραφή πριν δημιουργήσετε οτιδήποτε νέο· το κλειδί που χρειάζεστε μπορεί ήδη να υπάρχει.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Παράμετροι αιτήματος
- pageSize: αριθμός κλειδιών ανά σελίδα (προεπιλογή: επιστρέφονται όλα τα κλειδιά)
- paginationToken: διακριτικό για την ανάκτηση της επόμενης σελίδας, εάν ο αριθμός των κλειδιών υπερβαίνει το μέγεθος σελίδας
- aclFilters: φιλτράρισμα κλειδιών βάσει συγκεκριμένων δικαιωμάτων
Φιλτράρισμα βάσει ACL
Μπορείτε να ανακτήσετε μόνο κλειδιά με συγκεκριμένο επίπεδο πρόσβασης:
# Καταγραφή μόνο κλειδιών με πρόσβαση στο chat
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Αυτό το φιλτράρισμα καθιστά τον έλεγχο διαχειρίσιμο ακόμη και όταν ξεπερνάτε τα δώδεκα κλειδιά. Στην πράξη, δύο ερωτήματα προκύπτουν συχνά και απαντώνται με ένα μόνο αίτημα: ποιος μπορεί να καλέσει το πιο ακριβό μοντέλο και ποια κλειδιά εξακολουθούν να διαθέτουν χαρακτήρα μπαλαντέρ (wildcard). Το δεύτερο είναι το πιο χρήσιμο· ένα ξεχασμένο wildcard σε περιβάλλον παραγωγής αποτελεί το πιο συχνό σφάλμα διαμόρφωσης και το πιο αθόρυβο.
Σελιδοποίηση
Για ομάδες με πολλά κλειδιά, χρησιμοποιήστε τη σελιδοποίηση:
# Πρώτη σελίδα με 10 κλειδιά
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Επόμενη σελίδα με το ληφθέν διακριτικό
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Τροποποίηση υπάρχοντος κλειδιού
Η τροποποίηση αντί της εκ νέου δημιουργίας δεν αποτελεί απλή ευκολία: το μυστικό κλειδί παραμένει το ίδιο, επομένως δεν απαιτείται νέα ανάπτυξη. Αυτό σάς επιτρέπει να προσαρμόζετε όρια ή να περιορίζετε δικαιώματα χωρίς διακοπή της υπηρεσίας· επιπλέον, σε περίπτωση υποψίας, μπορείτε να μειώσετε τα δικαιώματα ενός κλειδιού μέσα σε δευτερόλεπτα, ενώ προετοιμάζετε την περιστροφή του.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v3",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 30,
"qpm": 1000,
"tpm": 3000000
}'
Τι μπορείτε να τροποποιήσετε
- name: μετονομασία του κλειδιού ώστε να αντανακλά αλλαγή στη χρήση του
- acls: προσθήκη ή αφαίρεση δικαιωμάτων (endpoints, μοντέλα)
- qps / qpm / tpm: προσαρμογή των ορίων ρυθμού
- expireTime: παράταση ή μείωση της περιόδου ισχύος
Τι δεν μπορείτε να τροποποιήσετε
- Το αναγνωριστικό κλειδιού (
api_key_id) παραμένει σταθερό - Το μυστικό κλειδί δεν αλλάζει κατά την τροποποίηση (χρησιμοποιήστε περιστροφή γι’ αυτό)
- Η ομάδα ιδιοκτησίας δεν μπορεί να μεταφερθεί
Έλεγχος διάδοσης
Αυτή είναι η λεπτομέρεια που εξηγεί τα μισά «σφάλματα» που αναφέρονται μετά την τροποποίηση ενός κλειδιού: η αλλαγή δεν είναι στιγμιαία σε όλους τους διακομιστές. Ένα νεοδημιουργημένο κλειδί μπορεί να επιστρέψει σφάλμα 401 για λίγα λεπτά, ένα διευρυμένο ACL μπορεί να μην είναι ακόμη ενεργό· και εσείς αναζητάτε το σφάλμα στον δικό σας κώδικα, ενώ αρκούσε απλώς να περιμένετε. Το endpoint διάδοσης υπάρχει ακριβώς για να εξαλείψει αυτή την αμφιβολία:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Αυτό το endpoint επιστρέφει την κατάσταση διάδοσης του κλειδιού. Περιμένετε να ολοκληρωθεί η διάδοση πριν χρησιμοποιήσετε το κλειδί σε περιβάλλον παραγωγής, ειδικά μετά την τροποποίηση των ACLs.
Συχνά σενάρια
Αναβάθμιση κλειδιού ανάπτυξης σε παραγωγής
Η μετάβαση σε περιβάλλον παραγωγής αποτελεί το πιο συχνό σενάριο τροποποίησης και η αντανακλαστική κίνηση δημιουργίας νέου κλειδιού σε αυτή την περίπτωση είναι δαπανηρή: πρέπει να το αναπτύξετε παντού, να ενημερώσετε τα vaults και το παλιό κλειδί παραμένει επ’ αόριστον. Η αύξηση των ορίων στο υπάρχον κλειδί αποφεύγει όλα αυτά.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-chatbot",
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}'
Περιορισμός κλειδιού με υποψία παραβίασης
Σε περίπτωση υποψίας, η σειρά των ενεργειών έχει σημασία. Ο περιορισμός πρώτα —κενά ACLs, μηδενικά όρια ρυθμού— σταματά τη διαρροή με ένα αίτημα, χωρίς να προκαλέσει μη αναστρέψιμη ζημιά. Η περιστροφή έρχεται αργότερα, εκτός σύνδεσης, μόλις εντοπίσετε πού χρησιμοποιήθηκε το κλειδί. Η αντίστροφη σειρά αφήνει την παραγωγή εκτός λειτουργίας και μια έρευνα που πρέπει να διεξαχθεί υπό πίεση.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"acls": [],
"qps": 0,
"qpm": 0
}'
Βασικά σημεία
- Το
GET /auth/teams/{teamId}/api-keysκαταγράφει όλα τα κλειδιά με σελιδοποίηση και φιλτράρισμα ACL - Το
PUT /auth/api-keys/{apiKeyId}τροποποιεί παραμέτρους χωρίς να αλλάζει το μυστικό κλειδί - Το
GET /auth/api-keys/{apiKeyId}/propagationεπαληθεύει ότι οι αλλαγές έχουν τεθεί σε ισχύ - Χρησιμοποιήστε το φιλτράρισμα ACL για να ελέγχετε τακτικά την πρόσβαση της ομάδας σας
- Μετά από κάθε τροποποίηση, ελέγξτε τη διάδοση πριν χρησιμοποιήσετε το κλειδί σε παραγωγή