Κλειδιά API και εμβέλειες

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

Τι επιτρέπεται να κάνει ένα κλειδί

Τρεις ρυθμίσεις του κλειδιού καθορίζουν τι μπορεί να δει και να αλλάξει ένα αίτημα με αυτό. Η καθεμία μόνο στενεύει τις άλλες.

Ρύθμιση	Τι ελέγχει
Ρόλος	`admin`, `editor`, `verifier` ή `viewer` – οι ίδιοι ρόλοι που έχουν οι άνθρωποι. Το κλειδί μπορεί να κάνει ό,τι μπορεί να κάνει ένας χρήστης με αυτόν τον ρόλο.
Εμβέλειες	Ποια μέρη του API επιτρέπεται να καλεί το κλειδί, για παράδειγμα `cards:read` ή `webhooks:manage`. Δείτε τον οδηγό Εμβέλειες κλειδιών.
Προφίλ δεδομένων	Προαιρετικό. Περιορίζει το κλειδί στις κατηγορίες γνώσης που επιτρέπει το προφίλ, όπως έναν χρήστη με αυτό το προφίλ.

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

Δώστε σε κάθε ενσωμάτωση το δικό της κλειδί με τον στενότερο ρόλο και τις εμβέλειες που χρειάζεται. Μια εργασία συγχρονισμού που μόνο γράφει έγγραφα δεν χρειάζεται admin· μια εργασία αναφορών δεν χρειάζεται εμβέλειες εγγραφής.

Δημιουργήστε ένα κλειδί

Ένας διαχειριστής του οργανισμού δημιουργεί κλειδιά στη Sursa στο Administration → API keys (διαχείριση, κλειδιά API) ή με το POST /v1/api-keys, χρησιμοποιώντας ένα κλειδί ή μια συνεδρία με τον ρόλο admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Η απόκριση περιέχει την τιμή του κλειδιού στο key. Εμφανίζεται μία φορά: η Sursa κρατά μόνο μια τιμή κατακερματισμού (hash) της και δεν μπορεί να την εμφανίσει ξανά. Ένα κλειδί έχει τη μορφή kb_ ακολουθούμενο από 43 χαρακτήρες· οι πρώτοι χαρακτήρες (prefix) εμφανίζονται στη λίστα των κλειδιών, ώστε να ξεχωρίζετε τα κλειδιά μεταξύ τους.

Χωρίς scopes, το κλειδί παίρνει τις εμβέλειες του ρόλου του. Περάστε scopes για να το περιορίσετε περισσότερο. Χωρίς expires_at, το κλειδί δεν λήγει.

Φυλάξτε τα κλειδιά μυστικά

Αποθηκεύετε τα κλειδιά σε διαχειριστή μυστικών ή σε μεταβλητές περιβάλλοντος της υπηρεσίας σας, ποτέ στον πηγαίο κώδικα.
Χρησιμοποιείτε τα κλειδιά μόνο από τους διακομιστές σας. Η Sursa δέχεται αιτήματα από προγράμματα περιήγησης (το CORS είναι ανοιχτό), αλλά ένα κλειδί σε μια ιστοσελίδα είναι ορατό σε όποιον την ανοίγει.
Μη στέλνετε ποτέ ένα κλειδί μέσα σε URL. Στέλνετέ το μόνο στην κεφαλίδα Authorization.
Αν ένα κλειδί διαρρεύσει, ανακαλέστε το αμέσως και δημιουργήστε νέο.

Ελέγξτε ένα κλειδί

Το GET /v1/me επιστρέφει το κλειδί, τον ρόλο του, τις πραγματικές εμβέλειες, το προφίλ δεδομένων, τη λήξη και το όριο ρυθμού. Λειτουργεί με οποιοδήποτε έγκυρο κλειδί, όποιες κι αν είναι οι εμβέλειές του, γι’ αυτό χρησιμοποιήστε το ως δοκιμή σύνδεσης της ενσωμάτωσής σας και όταν διερευνάτε ένα 403.

Εναλλαγή κλειδιού

Η εναλλαγή αντικαθιστά ένα κλειδί χωρίς να σταματήσει η ενσωμάτωση. Ο πιο γρήγορος τρόπος είναι η επανέκδοση του κλειδιού: το POST /v1/api-keys/{key_id}/roll εκδίδει μια νέα τιμή για το ίδιο κλειδί, με τον ίδιο ρόλο, τις ίδιες εμβέλειες, τις ίδιες συλλογές και την ίδια ημερομηνία λήξης. Η προηγούμενη τιμή εξακολουθεί να λειτουργεί για overlap_hours (24 ώρες από προεπιλογή, έως 168), ώστε στο μεταξύ να περάσετε τη νέα τιμή στην ενσωμάτωσή σας· το POST /v1/api-keys/{key_id}/revoke-previous τερματίζει νωρίτερα την επικάλυψη.

Για να αντικαταστήσετε αντίθετα ένα κλειδί με ένα διαφορετικό:

Δημιουργήστε ένα νέο κλειδί με τον ίδιο ρόλο, τις ίδιες εμβέλειες και το ίδιο προφίλ δεδομένων.
Ενημερώστε την ενσωμάτωσή σας με το νέο κλειδί.
Παρακολουθήστε το παλιό κλειδί στο Administration → API keys (ή το last_used στο GET /v1/api-keys), μέχρι να μη χρησιμοποιείται πια.
Ανακαλέστε το παλιό κλειδί.

Ορίζετε ημερομηνία λήξης στα κλειδιά και κάνετε την εναλλαγή τους πριν από αυτήν. Η Sursa προειδοποιεί τους διαχειριστές του οργανισμού πριν λήξει ένα κλειδί· ένα κλειδί που έχει λήξει επιστρέφει 401 με τον κωδικό api_keys.expired.

Ανάκληση κλειδιού

Ανακαλέστε ένα κλειδί στο Administration → API keys ή με το DELETE /v1/api-keys/{key_id}. Η ανάκληση ισχύει μέσα σε λίγα δευτερόλεπτα σε κάθε διακομιστή του API. Τα αιτήματα με ανακληθέν κλειδί επιστρέφουν 401 με τον κωδικό auth.not_authenticated.

Κλειδιά προσαρμοσμένης πηγής

Μια προσαρμοσμένη πηγή έχει το δικό της είδος κλειδιού. Ξεκινά με kbsrc_, μπορεί μόνο να γράφει έγγραφα σε αυτή τη μία πηγή και δεν μπορεί να διαβάσει ή να αναζητήσει τίποτα. Είναι το πιο ασφαλές κλειδί για να το δώσετε σε μια πλατφόρμα ενσωμάτωσης όπως το Zapier. Δημιουργήστε το στη σελίδα της πηγής, στην ενότητα API keys, ή με το POST /v1/sources/{source_id}/push-keys.

Όταν τα κλειδιά δεν είναι διαθέσιμα

Τα κλειδιά API είναι μέρος του πακέτου του οργανισμού. Αν το πακέτο δεν τα περιλαμβάνει, η δημιουργία κλειδιού και κάθε αίτημα με κλειδί επιστρέφουν 403 με τον κωδικό api_keys.feature_disabled.