Έλεγχος ταυτότητας

Έκδοση API 2026-10-affable-towhee

Κάθε κλήση στο Lingara API φέρει ένα διακριτικό πρόσβασης. Ένας διακομιστής το αποκτά ανταλλάσσοντας το αναγνωριστικό και το μυστικό ενός πελάτη OAuth στο endpoint διακριτικών: είναι η παραχώρηση client credentials του OAuth 2.0, για έναν διακομιστή που ενεργεί για λογαριασμό του εαυτού του. Δημιουργήστε πελάτες στη σελίδα Ενσωματώσεις της εφαρμογής web του Lingara, στη διεύθυνση app.getlingara.com/admin.

Συνεδρία ή πελάτης

Οι εφαρμογές του Lingara σας συνδέουν με μια συνεδρία, η οποία διαθέτει κάθε εύρος δικαιωμάτων και καταναλώνει το όριο χρήσης του προγράμματός σας. Ένας πελάτης είναι πιο περιορισμένος: επιλέγετε τα εύρη δικαιωμάτων που του επιτρέπονται όταν τον δημιουργείτε, και κάθε διακριτικό πρόσβασης που αποκτά φέρει μόνο τα εύρη δικαιωμάτων που ζητά.

Τρεις τιμές

Το αναγνωριστικό πελάτη αρχίζει με lgr_cid_ και ονομάζει τον πελάτη στο endpoint διακριτικών. Δεν είναι μυστικό.

Το μυστικό πελάτη αρχίζει με lgr_cs_ και αποστέλλεται μόνο στο endpoint διακριτικών. Εμφανίζεται μία φορά, όταν το δημιουργείτε: αντιγράψτε το τότε, επειδή το Lingara αποθηκεύει μόνο ένα hash του.

Το διακριτικό πρόσβασης αρχίζει με lgr_at_ και διαρκεί μία ώρα. Μπαίνει στην κεφαλίδα Authorization: Bearer των κλήσεων κάτω από το /v1/, και πουθενά αλλού. Είναι η μόνη τιμή που ανήκει σε αυτή την κεφαλίδα: ένα μυστικό πελάτη που στέλνεται εκεί απορρίπτεται με 401.

Αποκτήστε ένα διακριτικό πρόσβασης

Στείλτε με POST μια φόρμα στο endpoint διακριτικών με grant_type=client_credentials. Στείλτε το αναγνωριστικό και το μυστικό του πελάτη είτε με έλεγχο ταυτότητας HTTP Basic είτε ως τα πεδία φόρμας client_id και client_secret, ποτέ και με τους δύο τρόπους. Το scope είναι μια λίστα, χωρισμένη με κενά, από εύρη δικαιωμάτων που επιτρέπονται στον πελάτη· παραλείψτε το για να λάβετε κάθε εύρος δικαιωμάτων που επιτρέπεται στον πελάτη. Η παρακάτω εντολή ζητά μόνο το usage:read, το εύρος δικαιωμάτων που χρειάζεται το παράδειγμα GET /v1/usage πιο κάτω.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

Η απάντηση περιέχει access_token, token_type (Bearer), expires_in (3600, σε δευτερόλεπτα) και scope, τα εύρη δικαιωμάτων που έχει πράγματι το διακριτικό. Μια αποτυχημένη ανταλλαγή απαντά στη μορφή σφάλματος του OAuth, {error, error_description}, όχι στον φάκελο {code, error} του /v1/. Ένα λανθασμένο ή ανακληθέν μυστικό, ή ένας διαγραμμένος πελάτης, απορρίπτεται με 401 και invalid_client. Ένα εύρος δικαιωμάτων που ο πελάτης δεν μπορεί να ζητήσει απορρίπτει ολόκληρη την ανταλλαγή με 400 και invalid_scope· δεν περιορίζεται ποτέ σιωπηρά.

Ενέργεια για λογαριασμό άλλου χρήστη του Lingara

Μια εφαρμογή που ενεργεί για λογαριασμό άλλου χρήστη του Lingara χρησιμοποιεί την παραχώρηση κωδικού εξουσιοδότησης. Στείλτε το πρόγραμμα περιήγησης του χρήστη στο URL εξουσιοδότησης με response_type=code, client_id, ένα redirect_uri που ταιριάζει ακριβώς με ένα που έχετε καταχωρίσει, scope, state και ένα code_challenge S256. Ο χρήστης βλέπει τη σελίδα συναίνεσης του Lingara και επιστρέφει στο redirect_uri σας με code, state και iss. Ελέγξτε ότι το state είναι αυτό που στείλατε και ότι το iss είναι https://api.getlingara.com πριν χρησιμοποιήσετε τον κωδικό.

Το PKCE είναι υποχρεωτικό

Κάθε πελάτης χρησιμοποιεί PKCE, μόνο με τη μέθοδο S256. Δημιουργήστε ένα τυχαίο code_verifier, στείλτε τον κατακερματισμό SHA-256 του, κωδικοποιημένο σε base64url, ως code_challenge με code_challenge_method=S256, και κρατήστε το verifier για την ανταλλαγή. Ένα αίτημα χωρίς μέθοδο, ή με plain, απορρίπτεται με invalid_request.

Ανταλλάξτε τον κωδικό

Μέσα σε 60 δευτερόλεπτα, στείλτε POST στο endpoint διακριτικών με grant_type=authorization_code, code, το ίδιο redirect_uri και code_verifier, με έλεγχο ταυτότητας ως πελάτης· ένας δημόσιος πελάτης στέλνει μόνο το client_id. Η απάντηση προσθέτει ένα refresh_token, που αρχίζει με lgr_rt_. Ο κωδικός αρχίζει με lgr_ac_ και λειτουργεί μία φορά: μια δεύτερη χρήση απορρίπτεται με invalid_grant και τερματίζει τα διακριτικά που εξέδωσε η πρώτη ανταλλαγή.

Ανανέωση

Όταν λήξει το διακριτικό πρόσβασης, στείλτε POST στο endpoint διακριτικών με grant_type=refresh_token και το refresh_token, με έλεγχο ταυτότητας ξανά ως πελάτης. Κάθε ανανέωση επιστρέφει ένα νέο διακριτικό ανανέωσης: κρατήστε μόνο το νεότερο. Κάντε τις ανανεώσεις σας τη μία μετά την άλλη: ένα παλιό διακριτικό ανανέωσης που χρησιμοποιείται περισσότερα από 60 δευτερόλεπτα αφού αντικαταστάθηκε θεωρείται κλεμμένο και τερματίζει τα διακριτικά αυτής της εγκατάστασης με invalid_grant. Ένα διακριτικό ανανέωσης που δεν χρησιμοποιείται για 30 ημέρες λήγει. Το endpoint διακριτικών περιορίζει τα αιτήματα ανά διεύθυνση, οπότε ανανεώνετε μόνο όταν ένα διακριτικό εξαντληθεί.

Οι εγγενείς εφαρμογές είναι δημόσιοι πελάτες

Μια εφαρμογή υπολογιστή, κινητού ή γραμμής εντολών δεν μπορεί να κρατήσει ένα μυστικό, οπότε είναι δημόσιος πελάτης: δεν έχει μυστικό, στέλνει μόνο το client_id στο endpoint διακριτικών και καταχωρίζει μια ανακατεύθυνση loopback όπως http://127.0.0.1/callback (οποιαδήποτε θύρα) ή ένα σχήμα ιδιωτικής χρήσης όπως com.example.app:/callback. Ο χρήστης βλέπει τη σελίδα συναίνεσης κάθε φορά. Μια ιστοσελίδα δεν μπορεί να είναι πελάτης: ούτε το endpoint διακριτικών ούτε το /v1/ απαντούν σε cross-origin preflight.

Όταν ο χρήστης αφαιρέσει την εφαρμογή σας

Ο χρήστης μπορεί να αφαιρέσει την εφαρμογή σας ανά πάσα στιγμή από τις Συνδεδεμένες εφαρμογές, ή απεγκαθιστώντας την αν την εγκατέστησε, και η επόμενη κλήση της αποτυγχάνει με 401. Όταν ο χρήστης αποσυνδεθεί από την εφαρμογή σας, ανακαλέστε το διακριτικό ανανέωσής της στο endpoint ανάκλησης, κάτι που τερματίζει τα διακριτικά αυτής της εγκατάστασης.

Όταν λήξει το διακριτικό

Μετά από μία ώρα, το /v1/ απαντά 401 με τον κωδικό unauthorized και ένα σφάλμα που αρχίζει με invalid_token. Ανταλλάξτε ξανά όταν μια κλήση λάβει 401, ή λίγο πριν εξαντληθεί το expires_in, και επαναλάβετε την κλήση μία φορά. Αν η ίδια η ανταλλαγή αποτύχει με invalid_client ή invalid_scope, ο πελάτης ή το μυστικό του έχει διαγραφεί, ανακληθεί ή περιοριστεί: σταματήστε και διορθώστε το στη σελίδα Ενσωματώσεις, επειδή η επανάληψη δεν μπορεί να πετύχει. Κρατήστε το διακριτικό ανάμεσα στις κλήσεις: το endpoint διακριτικών περιορίζει τις ανταλλαγές ανά πελάτη και ανά διεύθυνση, και ένα πρόγραμμα που ανταλλάσσει σε κάθε κλήση απορρίπτεται με 429 και rate_limited μέσα στην ώρα (περιμένετε όσο ορίζει το Retry-After). Αυτή η παραχώρηση δεν έχει διακριτικό ανανέωσης: το μυστικό ανταλλάσσεται ξανά.

Τα διακριτικά πρόσβασης φτάνουν μόνο στις διαδρομές του API

Ένα διακριτικό πρόσβασης λειτουργεί μόνο σε διαδρομές κάτω από το /v1/. Αν σταλεί σε οποιαδήποτε άλλη διαδρομή του Lingara, απορρίπτεται με 401 και το σώμα αρχίζει με api_token_not_accepted, ως απλό κείμενο ή μέσα σε ένα πεδίο error, ποτέ στον φάκελο {code, error} που χρησιμοποιούν οι διαδρομές /v1/. Στείλτε το διακριτικό πρόσβασης στην κεφαλίδα Authorization, όπως παρακάτω.

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Εύρη δικαιωμάτων

Κάθε λειτουργία χρειάζεται ακριβώς ένα εύρος δικαιωμάτων, που αναφέρεται στη σελίδα της. Ένα διακριτικό πρόσβασης χωρίς αυτό το εύρος απορρίπτεται με 403 και τον κωδικό insufficient_scope. Για να καλέσετε τη λειτουργία, ζητήστε το εύρος δικαιωμάτων της κατά την ανταλλαγή, αν επιτρέπεται στον πελάτη. Ο παρακάτω πίνακας παραθέτει κάθε εύρος δικαιωμάτων και τις λειτουργίες που επιτρέπει.

Ποιος πληρώνει για μια κλήση

Ένας πελάτης χρεώνεται με έναν από δύο τρόπους, που επιλέγεται κατά τη δημιουργία του. Ένας πελάτης allowance καταναλώνει το όριο χρήσης του κατόχου του, το ίδιο όριο χρήσης με τις εφαρμογές σας, και το ίδιο κάνουν τα διακριτικά πρόσβασής του· το GET /v1/usage δείχνει τι απομένει. Ένας πελάτης metered δεν καταναλώνει όριο χρήσης: χρεώνεται ανά μονάδα πίστωσης μέσω μιας συνδρομής χρέωσης βάσει χρήσης που ρυθμίζετε στη σελίδα Ενσωματώσεις. Οι κλήσεις του απορρίπτονται με 402 και spend_cap_reached μόλις ο πελάτης ή ο λογαριασμός σας φτάσει το μηνιαίο όριο δαπανών του, και με 402 και metered_billing_inactive όσο η χρέωση βάσει χρήσης δεν είναι ενεργή. Ένα σχέδιο μαθήματος αντιστοιχεί σε 10 μονάδες πίστωσης, ένας γύρος με τον καθηγητή σε 1 και μια δημιουργία λεξιλογίου σε 3, οπότε οι units που αναφέρει το GET /v1/usage μετατρέπονται σε μονάδες πίστωσης με αυτά τα βάρη. Μια κλήση που κάνει μια εφαρμογή για λογαριασμό άλλου χρήστη, με διακριτικό από κωδικό εξουσιοδότησης, καταναλώνει πάντα το όριο χρήσης αυτού του χρήστη, ανεξάρτητα από τον τρόπο χρέωσης του πελάτη.

Κρατήστε μυστικά και διακριτικά σε διακομιστή

Το μυστικό πελάτη ανήκει σε έναν διακομιστή που ελέγχετε, ποτέ σε μια ιστοσελίδα, σε μια επέκταση προγράμματος περιήγησης ή σε ένα πακέτο εφαρμογής, όπου οποιοσδήποτε μπορεί να το διαβάσει. Μια εγγενής εφαρμογή είναι δημόσιος πελάτης και δεν κατέχει μυστικό. Ούτε το /v1/ ούτε το endpoint διακριτικών απαντούν σε cross-origin preflight, οπότε ένα πρόγραμμα περιήγησης σε άλλον ιστότοπο δεν μπορεί να τα καλέσει ούτως ή άλλως.

Διαχείριση πελατών

Στη σελίδα Ενσωματώσεις, στη διεύθυνση app.getlingara.com/admin, δημιουργήστε, μετονομάστε και διαγράψτε πελάτες, αλλάξτε τι μπορεί να κάνει ο καθένας και σε ποια έκδοση είναι δεσμευμένος, και δημιουργήστε και ανακαλέστε τα μυστικά του. Η διαγραφή ενός πελάτη σταματά αμέσως κάθε διακριτικό πρόσβασης που κατέχει και τερματίζει την παραχώρηση κάθε χρήστη προς αυτόν. Η ανάκληση ενός μυστικού σταματά αμέσως κάθε διακριτικό πρόσβασης που αποκτήθηκε με ανταλλαγή αυτού του μυστικού. Ο περιορισμός των εύρων δικαιωμάτων ενός πελάτη ισχύει επίσης αμέσως· η διεύρυνσή τους, ή η αλλαγή της έκδοσής του, ισχύει από την επόμενη ανταλλαγή.

Εναλλαγή μυστικού

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

Αν μια μετάφραση διαφέρει από την αγγλική τεκμηρίωση, ισχύει η αγγλική τεκμηρίωση.