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

Κάθε αίτημα προς το API της Sursa φέρει ένα κλειδί API ή ένα διακριτικό πρόσβασης OAuth μιας εφαρμογής στην κεφαλίδα Authorization:

Authorization: Bearer kb_3f9c…

Το κλειδί προσδιορίζει τον οργανισμό και καθορίζει τι μπορεί να δει και να αλλάξει το αίτημα: τον ρόλο του, τις εμβέλειές του, το προφίλ δεδομένων του και τις συλλογές του. Στη διεύθυνση του API δεν υπάρχουν συνεδρίες ούτε cookies. Κάθε αίτημα πιστοποιείται ξεχωριστά, γι’ αυτό μπορείτε να στέλνετε αιτήματα παράλληλα και από πολλούς διακομιστές με το ίδιο κλειδί.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Παλαιότερες ενσωματώσεις μπορεί να στέλνουν το κλειδί σε μια κεφαλίδα X-API-Key. Αυτή εξακολουθεί να γίνεται δεκτή, αλλά ο νέος κώδικας πρέπει να χρησιμοποιεί το Authorization: Bearer.

Είδη διαπιστευτηρίων

Διαπιστευτήριο	Μορφή	Πού λειτουργεί
Κλειδί API του οργανισμού	`kb_…`	Κάθε τελικό σημείο του API, στο πλαίσιο του ρόλου, των εμβελειών, του προφίλ δεδομένων και των συλλογών του.
Κλειδί προσαρμοσμένης πηγής	`kbsrc_…`	Μόνο τα τελικά σημεία αποστολής (push) της δικής του προσαρμοσμένης πηγής (`/v1/push/sources/{source_id}/…`).
Διακριτικό πρόσβασης OAuth	`kbat_…`	Τα τελικά σημεία της αναφοράς API, στο πλαίσιο των εμβελειών του διακριτικού. Ένα διακριτικό από το `POST /oauth/token` με κωδικό εξουσιοδότησης ενεργεί εκ μέρους του εργαζομένου που έδωσε τη συγκατάθεσή του· ένα διακριτικό `client_credentials` ενεργεί για τον οργανισμό, όπως ένα κλειδί API. Ισχύει για 1 ώρα.

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

Σφάλματα ελέγχου ταυτότητας

Κατάσταση και κωδικός	Τι σημαίνει	Τι να κάνετε
`401` `auth.not_authenticated`	Κανένα κλειδί, λάθος πληκτρολογημένο κλειδί ή ανακληθέν κλειδί.	Ελέγξτε την κεφαλίδα και την τιμή του κλειδιού.
`401` `api_keys.expired`	Η ημερομηνία λήξης του κλειδιού έχει παρέλθει.	Δημιουργήστε ένα νέο κλειδί και αντικαταστήστε το παλιό.
`401` `sources.push_key_invalid`	Ένα κλειδί προσαρμοσμένης πηγής είναι λάθος, έχει ανακληθεί ή ανήκει σε άλλη πηγή.	Ελέγξτε το κλειδί και το ID της πηγής στη διαδρομή.
`401` `oauth.token_expired`	Το διακριτικό πρόσβασης OAuth έχει λήξει.	Λάβετε ένα νέο με το διακριτικό ανανέωσης.
`403` `api_keys.scope`	Το κλειδί δεν έχει εμβέλεια για αυτή τη λειτουργία.	Προσθέστε την εμβέλεια ή χρησιμοποιήστε ένα κλειδί που την έχει.
`403` `api_keys.feature_disabled`	Το πακέτο του οργανισμού δεν περιλαμβάνει κλειδιά API.	Επικοινωνήστε με τον διαχειριστή του οργανισμού.
`403` `api_keys.ip_not_allowed`	Το αίτημα προέρχεται από διεύθυνση εκτός των επιτρεπόμενων διευθύνσεων του κλειδιού.	Καλέστε από ένα επιτρεπόμενο δίκτυο ή αλλάξτε τις διευθύνσεις του κλειδιού.
`403` `api_keys.mcp_only`	Ένα προσωπικό κλειδί MCP χρησιμοποιήθηκε εκτός του τελικού σημείου `/mcp`.	Για το API χρησιμοποιήστε ένα κλειδί API του οργανισμού.
`403` `oauth.operation_not_allowed`	Η λειτουργία δεν ανήκει στο δημόσιο API, γι’ αυτό ένα διακριτικό OAuth δεν μπορεί να την καλέσει.	Χρησιμοποιήστε μια λειτουργία από την αναφορά API.
`403` `org.suspended`	Ο οργανισμός έχει ανασταλεί. Τα δεδομένα του διατηρούνται.	Επικοινωνήστε με τον διαχειριστή του οργανισμού.

Το 403 σημαίνει ότι το αίτημα πιστοποιήθηκε, αλλά δεν επιτρέπεται. Ένα αντικείμενο που το κλειδί δεν επιτρέπεται να δει απαντά 404, όπως ένα αντικείμενο που δεν υπάρχει, ώστε ένα κλειδί να μην μπορεί να μάθει τι βρίσκεται έξω από την πρόσβασή του.

Εργασία ως προφίλ δεδομένων

Ένα κλειδί με τον ρόλο admin μπορεί να ελέγξει τι θα έβλεπε μια άλλη ομάδα ανθρώπων: η κεφαλίδα X-View-As εκτελεί ένα αίτημα ως προφίλ δεδομένων και, προαιρετικά, ως ρόλος.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Τα αιτήματα σε αυτή τη λειτουργία μόνο διαβάζουν: κάθε αλλαγή επιστρέφει 403 με τον κωδικό view_as.read_only. Ένα διακριτικό OAuth ή ένα κλειδί χωρίς τον ρόλο admin δεν μπορεί να χρησιμοποιήσει το X-View-As: απαντά 403 με τον κωδικό view_as.admin_key_required. Μια κεφαλίδα που δεν ονομάζει κανένα υπαρκτό προφίλ απαντά 400 με τον κωδικό view_as.invalid_header.

Εφαρμογές προγράμματος περιήγησης

Το API επιτρέπει αιτήματα από οποιοδήποτε origin ιστού (Access-Control-Allow-Origin: *) και δεν χρησιμοποιεί ποτέ cookies, οπότε μια σελίδα μπορεί να το καλέσει με fetch. Το κλειδί τότε βρίσκεται στη σελίδα και είναι ορατό σε όποιον τη χρησιμοποιεί. Καλείτε το API από το πρόγραμμα περιήγησης μόνο με ένα κλειδί που είστε διατεθειμένοι να δείξετε σε αυτούς τους χρήστες, όπως ένα κλειδί viewer περιορισμένο σε δημόσιες συλλογές, ή βάλτε τον δικό σας διακομιστή ανάμεσα στο πρόγραμμα περιήγησης και στη Sursa.

Τι μπορεί να κάνει μόνο ένας εργαζόμενος

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

Οι συνομιλίες ανήκουν σε ένα πρόσωπο. Ένα κλειδί API του οργανισμού βλέπει στο GET /v1/conversations μόνο τις συνομιλίες που ξεκίνησε το ίδιο. Το δημόσιο API δεν έχει λειτουργία που ξεκινά μια συνομιλία, οπότε για ένα κλειδί η λίστα είναι κανονικά κενή και οι συνομιλίες των εργαζομένων δεν εμφανίζονται ποτέ σε αυτό. Οι ερωτήσεις χωρίς συνομιλία, με POST /v1/ask ή POST /v1/chat, λειτουργούν με οποιοδήποτε κλειδί έχει την εμβέλεια ask. Για να δείτε τη λίστα με τις συνομιλίες ενός εργαζομένου και να διαβάσετε το ιστορικό μιας από αυτές με GET /v1/conversations/{conv_id}, καλέστε το API με ένα διακριτικό OAuth εκ μέρους αυτού του εργαζομένου. Το διακριτικό βλέπει μόνο τις συνομιλίες του ίδιου του εργαζομένου· κάθε άλλη συνομιλία απαντά 404 με τον κωδικό conversations.not_found.

Μόνο ένας εργαζόμενος επαληθεύει μια κάρτα. Η επαλήθευση επιβεβαιώνει ότι ένα πρόσωπο έλεγξε το περιεχόμενο, γι’ αυτό τα POST /v1/cards/{card_id}/verification/verify και POST /v1/cards/{card_id}/verify χρειάζονται μια συνεδρία ή ένα διακριτικό OAuth εκ μέρους ενός εργαζομένου που μπορεί να επαληθεύσει την κάρτα. Με ένα κλειδί API του οργανισμού ή ένα διακριτικό client_credentials απαντούν 400 με τον κωδικό cards.verify_user_account_required. Πρώτα γίνονται οι συνήθεις έλεγχοι: μια κάρτα που το κλειδί δεν μπορεί να δει απαντά 404 και ένα κλειδί που δεν επιτρέπεται να την επαληθεύσει απαντά 403.