Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Δημιουργία και διαμόρφωση κλειδιού API

Μάθημα 2 / 14 Ενημερώθηκε 29 Ιουλίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Γιατί να δημιουργείτε κλειδιά μέσω του API
  2. Σημείο τέλους (Endpoint) δημιουργίας
  3. Πλήρες παράδειγμα με curl
  4. Συνιστώμενες στρατηγικές ACL
  5. Διαθέσιμα σημεία τέλους ACL
  6. Βασικά σημεία

Γιατί να δημιουργείτε κλειδιά μέσω του API

Η χειροκίνητη δημιουργία ενός κλειδιού διαρκεί τριάντα δευτερόλεπτα—ακριβώς γι’ αυτόν τον λόγο χρειάζεστε αυτοματοποίηση. Επειδή είναι γρήγορη, το κάνετε χωρίς σκέψη: χωρίς σύμβαση ονοματοδοσίας, χωρίς όρια ρυθμού, απλώς ένα μπαλαντέρ «για να προχωρήσετε γρήγορα». Έξι μήνες αργότερα, κανείς δεν γνωρίζει τι κάνει το κάθε κλειδί.

Η χρήση του API σας αναγκάζει να ονομάζετε, να ορίζετε το πεδίο εφαρμογής και να θέτετε όρια σε κάθε κλειδί, καθώς αυτές είναι παράμετροι σεναρίου. Η συνέπεια παύει να είναι μια πειθαρχία που πρέπει να διατηρείτε και γίνεται ιδιότητα του κώδικα. Μπορείτε να αυτοματοποιήσετε τη δημιουργία κλειδιών για τα περιβάλλοντά σας (dev, staging, production), να εφαρμόσετε λεπτομερείς λίστες ελέγχου πρόσβασης (ACLs) και να ορίσετε όρια ρυθμού—όλα εντός των σεναρίων ανάπτυξης ή των εργαλείων υποδομής σας.

Σημείο τέλους (Endpoint) δημιουργίας

Για να δημιουργήσετε ένα κλειδί API, στείλτε ένα αίτημα POST στο παρακάτω σημείο τέλους:

POST /auth/teams/{teamId}/api-keys

Σώμα αιτήματος

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Λεπτομερείς παράμετροι

name (απαιτείται): ένα αναγνώσιμο αναγνωριστικό για το κλειδί σας. Επιλέξτε ένα περιγραφικό όνομα που να υποδεικνύει τη χρήση (prod-backend, staging-chatbot, dev-john). Αυτό το όνομα εμφανίζεται στην κονσόλα και στα αρχεία καταγραφής χρήσης.

acls (απαιτείται): η λίστα των δικαιωμάτων που χορηγούνται σε αυτό το κλειδί. Διατίθενται δύο μορφές:

  • api-key:endpoint:[endpoint] — περιορίζει τα προσβάσιμα σημεία τέλους (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] — περιορίζει τα διαθέσιμα μοντέλα (grok-4.20-0309-reasoning, grok-4.3, κ.λπ.)

Ο χαρακτήρας * λειτουργεί ως μπαλαντέρ: το api-key:endpoint:* εξουσιοδοτεί όλα τα σημεία τέλους, το api-key:model:* όλα τα μοντέλα. Κρατήστε το για τοπική ανάπτυξη. Στην παραγωγή, ένα μπαλαντέρ σημαίνει ότι ένα compromised κλειδί παρέχει πρόσβαση σε ό,τι μπορεί να κάνει η ομάδα σας—συμπεριλαμβανομένων των πιο δαπανηρών μοντέλων, τα οποία η εφαρμογή σας μπορεί να μην χρησιμοποιεί ποτέ.

qps (προαιρετικό): ερωτήματα ανά δευτερόλεπτο — μέγιστος αριθμός αιτημάτων ανά δευτερόλεπτο.

qpm (προαιρετικό): ερωτήματα ανά λεπτό — μέγιστος αριθμός αιτημάτων ανά λεπτό.

tpm (προαιρετικό): tokens ανά λεπτό — μέγιστος αριθμός tokens που επεξεργάζονται ανά λεπτό.

expireTime (προαιρετικό): ημερομηνία λήξης σε μορφή ISO 8601. Το κλειδί θα απενεργοποιηθεί αυτόματα σε αυτή την ημερομηνία.

Πλήρες παράδειγμα με curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

Η απόκριση περιέχει το μυστικό κλειδί, το οποίο δεν θα εμφανιστεί ποτέ ξανά. Αυτός ο κανόνας έχει μια πρακτική συνέπεια που πρέπει να προβλέψετε πριν εκτελέσετε το σενάριο, όχι μετά: αν δημιουργείτε κλειδιά σε βρόχο, η αποθήκευση πρέπει να γίνεται στην ίδια κίνηση. Ένα κλειδί που χάνεται μεταξύ της δημιουργίας και της καταγραφής δεν ανακτάται—πρέπει να το διαγράψετε και να ξεκινήσετε από την αρχή. Γράψτε το σε ένα θησαυροφυλάκιο (Vault, AWS Secrets Manager) και όχι στην τυπική έξοδο του τερματικού σας, όπου θα καταλήξει στο ιστορικό σας.

Συνιστώμενες στρατηγικές ACL

Κλειδί ανάπτυξης (ευρύ)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ιδανικό για τοπική ανάπτυξη: η πρόσβαση είναι ευρεία επειδή δεν γνωρίζετε εκ των προτέρων τι θα δοκιμάσετε, αλλά τα όρια ρυθμού παραμένουν χαμηλά. Αυτός είναι ο σωστός συμβιβασμός—ένας ατέρμονος βρόχος γραμμένος κατά λάθος ένα βράδυ Παρασκευής θα κοστίσει μερικά σεντς αντί για μερικές εκατοντάδες ευρώ.

Κλειδί παραγωγής (περιορισμένο)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

Στην παραγωγή, ο κανόνας αντιστρέφεται: ξεκινήστε από αυτό που κάνει πραγματικά η εφαρμογή και εξουσιοδοτήστε μόνο αυτό. Η ερώτηση που πρέπει να κάνετε κατά τη συγγραφή του ACL είναι πάντα η ίδια—αν αυτό το κλειδί διαρρεύσει αύριο, τι μπορεί να κάνει ένας τρίτος με αυτό; Ένα κλειδί περιορισμένο στο chat σε ένα μόνο μοντέλο και με όριο δέκα αιτημάτων ανά δευτερόλεπτο δίνει μια σύντομη απάντηση.

Προσωρινό κλειδί (με λήξη)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Η αυτόματη λήξη λύνει το πρόβλημα που κανείς δεν διαχειρίζεται: τα κλειδιά που οι άνθρωποι ξεχνούν να διαγράψουν. Ένα POC, μια επίδειξη, ένας προσωρινός συνεργάτης—σε όλες αυτές τις περιπτώσεις, το expireTime εγγυάται ότι η πρόσβαση θα απενεργοποιηθεί μόνη της. Αυτός είναι ο μόνος αξιόπιστος τρόπος διατήρησης ενός καθαρού ευρετηρίου, επειδή δεν βασίζεται στη μνήμη κανενός.

Διαθέσιμα σημεία τέλους ACL

Για να δείτε τα σημεία τέλους που μπορείτε να χρησιμοποιήσετε στα ACLs, συμβουλευτείτε:

GET /auth/teams/{teamId}/endpoints

Τα διαθέσιμα σημεία τέλους είναι: chat, embed, image, models, sample, tokenize, documents. Αυτή η λίστα μπορεί να εξελιχθεί με την πάροδο του χρόνου, οπότε ελέγχετε τακτικά.

Βασικά σημεία

  • Η δημιουργία κλειδιού γίνεται μέσω POST /auth/teams/{teamId}/api-keys
  • Τα ACLs ακολουθούν τη μορφή api-key:endpoint:[name] ή api-key:model:[name]
  • Το μπαλαντέρ * χορηγεί πλήρη πρόσβαση σε όλα τα σημεία τέλους ή τα μοντέλα
  • Το μυστικό κλειδί εμφανίζεται μόνο μία φορά κατά τη δημιουργία—αποθηκεύστε το αμέσως
  • Ορίζετε πάντα όρια ρυθμού (qps, qpm, tpm) κατάλληλα για τη χρήση
  • Χρησιμοποιήστε το expireTime για προσωρινά κλειδιά