Εμβέλειες κλειδιών
Μια εμβέλεια ονομάζει ένα μέρος του API που επιτρέπεται να καλεί ένα κλειδί. Κάθε τελικό σημείο της αναφοράς
API δηλώνει τη μία εμβέλεια που χρειάζεται. Ένα αίτημα με κλειδί που δεν την έχει απορρίπτεται με 403
και τον κωδικό api_keys.scope, πριν διαβαστεί ή αλλάξει οτιδήποτε.
Οι εμβέλειες λένε ποιες λειτουργίες επιτρέπεται να καλεί ένα κλειδί. Ο ρόλος, το προφίλ δεδομένων και οι συλλογές του
κλειδιού εξακολουθούν να καθορίζουν ποια αντικείμενα βλέπουν αυτές οι λειτουργίες: ένα κλειδί με cards:write και
τον ρόλο viewer δεν μπορεί να αλλάξει κάρτες, και ένα κλειδί περιορισμένο σε μία συλλογή δεν βλέπει τις άλλες.
Εμβέλειες
| Εμβέλεια | Επιτρέπει |
|---|---|
cards:read | Ανάγνωση καρτών, συλλογών και φακέλων. |
cards:write | Δημιουργία, αλλαγή και διαγραφή καρτών, συλλογών και φακέλων. |
search | Αναζήτηση στη βάση γνώσεων (POST /v1/search). |
ask | Ερωτήσεις στον Βοηθό AI (POST /v1/ask, POST /v1/chat). |
import:write | Εγγραφή στις προσαρμοσμένες πηγές του οργανισμού: συγχρονισμοί, παρτίδες και διαγραφές, καθώς και ανάγνωση της κατάστασής τους. Η δημιουργία μιας πηγής και των κλειδιών της χρειάζεται admin. |
webhooks:manage | Διαχείριση των webhooks και ανάγνωση της τροφοδοσίας συμβάντων (GET /v1/webhook-events). Και τα δύο χρειάζονται επίσης τον ρόλο admin. |
users:read | Ανάγνωση χρηστών και ομάδων. |
users:write | Αλλαγή χρηστών και ομάδων. |
analytics:read | Ανάγνωση αναλυτικών στοιχείων. |
audit:read | Ανάγνωση του αρχείου ελέγχου. |
finance:read | Ανάγνωση οικονομικών αναφορών, τιμολογίων και πληρωμών. |
catalog:read | Ανάγνωση του καταλόγου υπηρεσιών. |
files:read | Ανάγνωση αρχείων που δημιουργήθηκαν, όπως εξαγόμενες απαντήσεις. |
files:write | Αλλαγή και διαγραφή αρχείων που δημιουργήθηκαν. |
permissions:manage | Ανάθεση και ανάκληση δικαιωμάτων σε αντικείμενα. |
admin | Οι ρυθμίσεις του οργανισμού και τα κλειδιά API του. Ένα κλειδί με admin έχει επίσης κάθε άλλη εμβέλεια. |
Η αναζήτηση και οι ερωτήσεις είναι από τη φύση τους αναγνώσεις: ένα κλειδί που επιτρέπεται μόνο να διαβάζει μπορεί και πάλι να κάνει αναζητήσεις και ερωτήσεις.
Επιλογή εμβελειών
Δίνετε τις εμβέλειες που χρησιμοποιεί μια ενσωμάτωση και τίποτε άλλο:
| Ενσωμάτωση | Εμβέλειες |
|---|---|
| Bot ερωτήσεων και απαντήσεων σε εργαλείο συνομιλίας | search, ask |
| Εισαγωγή από το σύστημα εγγράφων σας | cards:write (API καρτών) ή import:write (προσαρμοσμένη πηγή) |
| Εξαγωγή σε αποθήκη δεδομένων | cards:read, users:read και webhooks:manage για την τροφοδοσία συμβάντων |
| Δημιουργία χρηστών από το σύστημα ανθρώπινου δυναμικού σας | users:write |
Περάστε τη λίστα όταν δημιουργείτε το κλειδί:
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'Παλαιότερες εμβέλειες
Τα κλειδιά που δημιουργήθηκαν πριν από τον διαχωρισμό των εμβελειών συνεχίζουν να λειτουργούν. Οι εμβέλειές τους
read, write και admin αντιστοιχούν στα εξής σύνολα:
| Παλαιότερη εμβέλεια | Σημαίνει |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | όλα όσα περιλαμβάνει το read, και επιπλέον cards:write, files:write, users:write, permissions:manage |
admin | κάθε εμβέλεια |
Ένα κλειδί που δημιουργήθηκε χωρίς ρητές εμβέλειες τις παίρνει από τον ρόλο του: το admin παίρνει admin· τα
editor και verifier παίρνουν write· το viewer παίρνει read.
Προβολή των εμβελειών ενός κλειδιού
Το GET /v1/me επιστρέφει τις εμβέλειες του κλειδιού που κάνει το αίτημα, όποιες εμβέλειες
κι αν έχει. Για ένα κλειδί που δημιουργήθηκε χωρίς ρητές εμβέλειες, αυτές είναι οι παλαιότερες εμβέλειες του ρόλου
του, όπως read και write· ο παραπάνω πίνακας δείχνει τι σημαίνουν. Όταν μια λειτουργία αποτυγχάνει με
api_keys.scope, το error.message κατονομάζει την εμβέλεια που έλειπε.