Πιστοποίηση με διακριτικό Bearer
Σε αυτήν τη σελίδα
Ασφαλίστε τις κλήσεις API σας
Κάθε αίτημα που αποστέλλεται στο API της xAI πρέπει να πιστοποιείται. Το API χρησιμοποιεί το σχήμα Bearer token, ένα ευρέως υιοθετημένο πρότυπο για REST APIs. Αυτό το μάθημα εξηγεί πώς λειτουργεί ο μηχανισμός και τις βέλτιστες πρακτικές για την προστασία των κλειδιών σας σε περιβάλλον παραγωγής.
Το σχήμα Bearer token
Όπως υποδηλώνει το όνομα, όποιος κατέχει («φέρει») το διακριτικό μπορεί να accesses το API. Γι’ αυτόν τον λόγο η προστασία του κλειδιού σας είναι θεμελιώδης: δεν υπάρχει έλεγχος ταυτότητας πέρα από το ίδιο το διακριτικό.
Μορφή κεφαλίδας
Κάθε αίτημα HTTP πρέπει να περιλαμβάνει την κεφαλίδα Authorization με το πρόθεμα Bearer ακολουθούμενο από το κλειδί σας:
Authorization: Bearer xai-your-api-key
Με cURL, αυτό δίνει:
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-4.5", "input": "Hello"}'
Στην Python, τα SDK διαχειρίζονται αυτήν την κεφαλίδα αυτόματα όταν περνάτε το κλειδί στον κατασκευαστή του client.
Σφάλματα πιστοποίησης
HTTP 401 Unauthorized
Αυτό το σφάλμα σημαίνει ότι το κλειδί σας λείπει, είναι άκυρο ή έχει ανακληθεί. Ελέγξτε:
- Ότι η μεταβλητή περιβάλλοντος
XAI_API_KEYέχει οριστεί - Ότι το κλειδί ξεκινά με
xai- - Ότι το κλειδί δεν έχει ανακληθεί στην κονσόλα
HTTP 403 Forbidden
Το κλειδί σας είναι έγκυρο, αλλά δεν διαθέτει τα δικαιώματα που απαιτούνται για την ζητούμενη ενέργεια. Αυτό μπορεί να συμβεί με περιορισμούς ομάδας σε ορισμένες λειτουργίες.
Βέλτιστες πρακτικές ασφαλείας
Ποτέ μην εκθέτετε ένα κλειδί στον κώδικα
Τα κλειδιά δεν πρέπει ποτέ να εμφανίζονται ως απλό κείμενο σε:
- Κώδικα πηγής με έλεγχο εκδόσεων (Git)
- Αρχεία καταγραφής εφαρμογών (logs)
- URLs ή παραμέτρους ερωτήματος
- Μηνύματα σφάλματος που εμφανίζονται στους χρήστες
- Ζητήματα (issues) και αιτήματα συγχώνευσης (pull requests) στο GitHub
Χρησιμοποιήστε ένα θησαυροφυλάκιο μυστικών
Σε περιβάλλον παραγωγής, αποθηκεύστε τα κλειδιά σας σε ένα αφιερωμένο σύστημα:
- AWS Secrets Manager ή Parameter Store
- Google Secret Manager
- Azure Key Vault
- HashiCorp Vault
- Μυστικά της πλατφόρμας CI/CD σας (GitHub Actions, GitLab CI)
Περιστροφή κλειδιών
Αλλάζετε τα κλειδιά σας τακτικά και αμέσως εάν υποψιάζεστε διαρροή:
- Δημιουργήστε ένα νέο κλειδί στην κονσόλα xAI
- Ενημερώστε το κλειδί στο θησαυροφυλάκιο μυστικών σας
- Αναπτύξτε εκ νέου την εφαρμογή σας
- Ελέγξτε ότι όλα λειτουργούν με το νέο κλειδί
- Ανακαλέστε το παλιό κλειδί στην κονσόλα
Περιορισμός δικαιωμάτων
Εάν εργάζεστε σε ομάδα, δημιουργήστε ξεχωριστά κλειδιά για κάθε υπηρεσία και περιβάλλον. Εάν ένα compromised, ο αντίκτυπος παραμένει περιορισμένος σε ένα μόνο πλαίσιο.
Ανίχνευση διαρροών
Το πρόθεμα xai- επιτρέπει στα εργαλεία ανίχνευσης (σάρωση μυστικών GitHub, GitGuardian, TruffleHog) να εντοπίζουν αυτόματα τα κλειδιά στον κώδικα πηγής. Ενεργοποιήστε αυτά τα εργαλεία στα αποθετήριά σας ώστε να ειδοποιείστε αμέσως σε περίπτωση τυχαίας αποκάλυψης.
Εάν εντοπιστεί ένα κλειδί σε ένα δημόσιο commit:
- Ανακαλέστε το αμέσως στην κονσόλα xAI
- Ελέγξτε το ιστορικό χρήσης σας για δόλια χρήση
- Δημιουργήστε ένα νέο κλειδί
- Καθαρίστε το ιστορικό Git σας (ή καλύτερα, θεωρήστε το κλειδί compromised και προχωρήστε)
Απαιτείται HTTPS
Το API xAI δέχεται μόνο συνδέσεις HTTPS. Το TLS κρυπτογραφεί τα αιτήματά σας κατά τη μεταφορά, συμπεριλαμβανομένης της κεφαλίδας Authorization. Μην προσπαθήσετε ποτέ να παρακάμψετε αυτήν την προστασία: ένα αίτημα μέσω μη κρυπτογραφημένου HTTP θα εξέθετε το κλειδί σας στο δίκτυο.
Βασικά σημεία
- Το API χρησιμοποιεί το σχήμα Bearer token μέσω της κεφαλίδας
Authorization - Το κλειδί είναι ο μοναδικός παράγοντας πιστοποίησης: προστατέψτε το όπως έναν κωδικό πρόσβασης
- Χρησιμοποιήστε ένα θησαυροφυλάκιο μυστικών σε παραγωγή και ποτέ μην κωδικοποιείτε ένα κλειδί απευθείας (hard-code)
- Ενεργοποιήστε την ανίχνευση διαρροών στα αποθετήρια Git σας
- Περιστρέφετε τα κλειδιά τακτικά και ανακαλείτε αμέσως οποιοδήποτε compromised κλειδί
Ελέγξτε την κατανόησή σας
Τα θεμέλια του API xAI: ένας τελευταίος έλεγχος πριν ξεκινήσετε την ανάπτυξη.
1. Τι πρέπει να κάνετε με ένα κλειδί API μόλις το δημιουργήσετε;
Απάντηση: Αποθηκεύστε το σε ασφαλές μέρος (εμφανίζεται μόνο μία φορά), εκθέστε το μέσω της μεταβλητής XAI_API_KEY αντί να το κωδικοποιήσετε απευθείας, χρησιμοποιήστε ένα κλειδί ανά περιβάλλον και δοκιμάστε το αμέσως με μια κλήση στο /v1/models.
2. Ποιο είναι το βασικό URL και γιατί έχει τόσο μεγάλη σημασία;
Απάντηση: https://api.x.ai/v1. Αυτό καθιστά δυνατή τη συμβατότητα με την OpenAI: η αλλαγή του base_url και του κλειδιού αρκεί για να κατευθύνετε τον υπάρχοντα κώδικα OpenAI στο Grok.
3. Ποια SDK μπορείτε να χρησιμοποιήσετε με το Grok;
Απάντηση: Το εγγενές xAI SDK, το OpenAI SDK (με το xAI base_url) και το Vercel AI SDK στην πλευρά JavaScript, συν το cURL για δοκιμές: το οικοσύστημα είναι ανοιχτό.
4. Ποιο είναι το κύριο endpoint δημιουργίας;
Απάντηση: POST /v1/responses, η σύγχρονη μορφή· το chat/completions παραμένει διαθέσιμο ως legacy επιλογή για συμβατότητα.
5. Πώς πιστοποιείται κάθε αίτημα;
Απάντηση: Με την κεφαλίδα Authorization: Bearer και το κλειδί xai-…: το πρότυπο σχήμα Bearer token, το ίδιο ανεξάρτητα από το SDK ή το εργαλείο.
Ένα ασφαλές κλειδί, το βασικό URL, η επιλογή SDK σας, Bearer παντού: τα θεμέλια έχουν τεθεί και τα επόμενα μαθήματα API βασίζονται σε αυτά.