Κλειδιά API

Κάθε κλήση στο REST API του Joryio ελέγχεται ως προς την ταυτότητα με ένα κλειδί API. Τα κλειδιά ισχύουν για έναν μόνο χώρο εργασίας, φέρουν μια ρητή λίστα δικαιωμάτων και μπορούν να περιοριστούν σε ένα σύνολο διευθύνσεων IP.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com - δείτε Επισκόπηση API.

Δημιουργία κλειδιού

1. Ανοίξτε το dashboard του Joryio και μεταβείτε στις Ρυθμίσεις → Κλειδιά API.
2. Κάντε κλικ στη Δημιουργία κλειδιού API.
3. Δώστε στο κλειδί ένα όνομα και (προαιρετικά) μια περιγραφή που θα βλέπουν οι συνάδελφοί σας.
4. Προαιρετικά προσθέστε μια λίστα επιτρεπόμενων IP - λίστα από CIDR ή μεμονωμένες IP, χωρισμένες με κόμμα ή κενό. Αφήστε την κενή για να επιτρέπεται οποιαδήποτε IP.
5. Επιλέξτε τα δικαιώματα που χρειάζεται αυτό το κλειδί. Επιλέξτε το μικρότερο σύνολο που λειτουργεί - δείτε τον κατάλογο scopes παρακάτω.
6. Κάντε κλικ στη Δημιουργία κλειδιού.

Εμφάνιση μίας φοράς

Η πλήρης τιμή του κλειδιού εμφανίζεται ακριβώς μία φορά, αμέσως μετά τη δημιουργία, και ποτέ ξανά. Αντιγράψτε την στον διαχειριστή μυστικών σας (1Password, Vault, AWS Secrets Manager κ.λπ.) πριν κλείσετε το παράθυρο. Αν τη χάσετε, διαγράψτε το κλειδί και δημιουργήστε νέο - το Joryio δεν μπορεί να ανακτήσει το αρχικό.

Η μορφή του κλειδιού είναι jry_live_<random> για κλειδιά παραγωγής και jry_test_<random> για δοκιμαστικά κλειδιά. Το ορατό πρόθεμα του κλειδιού (jry_live_abc123) εμφανίζεται στη λίστα κλειδιών του dashboard και στα logs διακομιστή, ώστε να μπορείτε να εντοπίσετε ποιο κλειδί έκανε τι χωρίς να εκτεθεί η πλήρης τιμή.

Χρήση κλειδιού

Στείλτε το κλειδί ως bearer token στην κεφαλίδα Authorization σε κάθε αίτημα:

GET /users/by-user-id/user_123
Host: api-eu1.joryio.com
Authorization: Bearer jry_live_98f31a72…
Content-Type: application/json

Κατάλογος scopes

Τα δικαιώματα ακολουθούν τη μορφή <resource>:<verb>. Τα ρήματα που χρησιμοποιούνται:

Ρήμα	Σημασία	Παράδειγμα
read	Λίστα ή ανάκτηση υπαρχουσών εγγραφών	users:read, campaigns:read
write	Δημιουργία ή ενημέρωση εγγραφών	users:write, segments:write
send	Ενεργοποίηση ενέργειας παράδοσης / αποστολής	campaigns:send
delete	Οριστική αφαίρεση εγγραφών	users:delete, campaigns:delete
track	Αποστολή συμβάντων αναλυτικών στοιχείων	events:track
activate	Έναρξη/παύση/συνέχιση ενός ενεργού workflow	canvas:activate
alias	Σύνδεση/αποσύνδεση εναλλακτικών αναγνωριστικών	users:alias
merge	Συγχώνευση δύο προφίλ χρηστών	users:merge
export	Μαζική εξαγωγή εγγραφών	users:export

Ακολουθεί ο πλήρης δημόσιος κατάλογος - επιστρέφεται επίσης από το GET /api-keys/permissions:

Συμβάντα

Scope	Τι επιτρέπει
events:track	Αποστολή προσαρμοσμένων συμβάντων από τους διακομιστές σας ή το SDK.
events:read	Ερωτήματα σε συμβάντα που έχουν καταγραφεί.

Χρήστες

Scope	Τι επιτρέπει
users:read	Αναζήτηση προφίλ χρηστών και γνωρισμάτων βάσει ID.
users:write	Δημιουργία ή ενημέρωση γνωρισμάτων και ιδιοτήτων χρηστών.
users:delete	Οριστική αφαίρεση προφίλ χρηστών (GDPR / δικαίωμα διαγραφής).
users:alias	Σύνδεση ή αποσύνδεση εξωτερικών ID και ψευδωνύμων email σε χρήστη.
users:merge	Συγχώνευση δύο προφίλ χρηστών σε ένα.
users:export	Μαζική εξαγωγή προφίλ χρηστών για ανάλυση εκτός σύνδεσης.

Καμπάνιες

Scope	Τι επιτρέπει
campaigns:read	Λίστα καμπανιών και προβολή της ρύθμισής τους.
campaigns:write	Δημιουργία ή επεξεργασία προσχεδίων καμπανιών μέσω API.
campaigns:send	Ενεργοποίηση αποστολής καμπάνιας σε συγκεκριμένο χρήστη ή τμήμα.
campaigns:delete	Οριστική αφαίρεση καμπανιών από αυτόν τον χώρο εργασίας.

Τμήματα

Scope	Τι επιτρέπει
segments:read	Λίστα τμημάτων και προβολή πλήθους μελών.
segments:write	Δημιουργία ή ενημέρωση ορισμών τμημάτων.
segments:delete	Οριστική διαγραφή τμημάτων και του ιστορικού τους.

Journeys χρηστών

Scope	Τι επιτρέπει
canvas:read	Λίστα journeys χρηστών και επιθεώρηση του γράφου βημάτων τους.
canvas:write	Δημιουργία ή επεξεργασία προσχεδίων journeys χρηστών.
canvas:activate	Έναρξη, παύση ή συνέχιση ενός ενεργού journey χρηστών.
canvas:delete	Αφαίρεση journeys χρηστών και του ιστορικού τους.

Πρότυπα

Scope	Τι επιτρέπει
templates:read	Ανάκτηση περιεχομένου προτύπων email, SMS και push.
templates:write	Δημιουργία ή επεξεργασία επαναχρησιμοποιήσιμων προτύπων μηνυμάτων.
templates:delete	Οριστική διαγραφή προτύπων από το Brand Studio.

Συνδρομές

Scope	Τι επιτρέπει
subscriptions:read	Προβολή της κατάστασης εγγραφής (opt-in) ενός χρήστη σε όλα τα κανάλια.
subscriptions:write	Εγγραφή ή απεγγραφή χρηστών από ομάδες και κανάλια.

Εφαρμογές και κλειδιά SDK

Scope	Τι επιτρέπει
apps:read	Λίστα των εφαρμογών και κλειδιών SDK που είναι καταχωρισμένα σε αυτόν τον χώρο εργασίας.
apps:write	Προσθήκη, εναλλαγή ή αφαίρεση κλειδιών SDK για εφαρμογές κινητών και web.

Βιβλιοθήκη στοιχείων

Scope	Τι επιτρέπει
assets:read	Ανάκτηση εικόνων, γραμματοσειρών και άλλων κοινόχρηστων πολυμέσων.
assets:write	Μεταφόρτωση, μετονομασία ή διαγραφή αρχείων στη βιβλιοθήκη στοιχείων.

Οντότητες

Scope	Τι επιτρέπει
entities:read	Ερωτήματα σε εγγραφές οντοτήτων (προϊόντα, άρθρα, τοποθεσίες…).
entities:write	Δημιουργία ή ενημέρωση εγγραφών οντοτήτων και των ιδιοτήτων τους.

Αναλυτικά στοιχεία

Scope	Τι επιτρέπει
analytics:read	Άντληση συγκεντρωτικών μετρικών, funnels και δεδομένων αναφορών.

Παραδοσιμότητα

Scope	Τι επιτρέπει
email_suppression:read	Επιθεώρηση της λίστας καταστολής email (bounces, καταγγελίες, μη αυτόματες).
email_suppression:write	Προσθήκη ή αφαίρεση εγγραφών από τη λίστα καταστολής email.
sms_suppression:read	Επιθεώρηση της λίστας καταστολής SMS (απαντήσεις STOP, αποτυχίες).
sms_suppression:write	Προσθήκη ή αφαίρεση αριθμών τηλεφώνου από τη λίστα καταστολής SMS.

Όρια συχνότητας

Scope	Τι επιτρέπει
touching_rules:read	Επιθεώρηση κανόνων ορίων συχνότητας και των τρεχόντων μετρητών τους.
touching_rules:write	Δημιουργία, επεξεργασία ή αφαίρεση κανόνων ορίων συχνότητας.

WhatsApp

Scope	Τι επιτρέπει
whatsapp:read	Ανάγνωση της ρύθμισης λογαριασμού WhatsApp Business.
whatsapp:write	Ενημέρωση της ρύθμισης λογαριασμού WhatsApp Business.

AI Agents

Scope	Τι επιτρέπει
ai_agents:read	Λίστα AI agents και της ρύθμισής τους.
ai_agents:write	Δημιουργία ή επεξεργασία AI agents και των ρυθμίσεων παρόχου τους.

Λίστα επιτρεπόμενων IP

Μπορείτε να δεσμεύσετε ένα κλειδί σε ένα σταθερό σύνολο IP προέλευσης. Όταν η λίστα είναι κενή, γίνονται δεκτά αιτήματα από οποιαδήποτε IP (η προεπιλογή). Όταν έχει εγγραφές, περνούν μόνο αιτήματα των οποίων η IP προέλευσης ταιριάζει με τουλάχιστον μία εγγραφή.

Αποδεκτή σύνταξη

• Σκέτη διεύθυνση IPv4 - 203.0.113.42
• Εύρος IPv4 CIDR - 10.0.0.0/24, 192.168.1.0/16
• Διεύθυνση IPv6 - μόνο ακριβής αντιστοίχιση (χωρίς CIDR για IPv6 ακόμη)

Συνδυάστε πολλαπλές εγγραφές χωρίζοντάς τες με κόμμα στο dashboard:

10.0.0.0/24, 203.0.113.42, 2001:db8::1

Ανάλυση της IP προέλευσης

Η IP πελάτη προσδιορίζεται από την αξιόπιστη κεφαλίδα του edge δικτύου (ορίζεται εκ νέου σε κάθε αίτημα στο edge - μια τιμή παρεχόμενη από τον πελάτη δεν μπορεί να επιβιώσει), με εφεδρεία τη διεύθυνση σύνδεσης του αξιόπιστου proxy. Η αριστερότερη, ελεγχόμενη από τον πελάτη, εγγραφή του X-Forwarded-For δεν χρησιμοποιείται σκόπιμα, ώστε η λίστα να μην μπορεί να παραπλανηθεί. Οι διευθύνσεις IPv6 με αντιστοίχιση IPv4 (::ffff:203.0.113.42) κανονικοποιούνται στη μορφή IPv4 πριν από τη σύγκριση.

Μορφή απορριφθέντος αιτήματος

Όταν ένα αίτημα προέρχεται από IP εκτός λίστας, το API επιστρέφει 401 Unauthorized με:

{
  "statusCode": 401,
  "message": "Request IP is not allowed for this API key",
  "timestamp": "2026-05-12T08:14:00.000Z",
  "path": "/users"
}

Η απόρριψη καταγράφεται στον διακομιστή με το πρόθεμα του κλειδιού και την επίμαχη IP, ώστε να μπορείτε να την ελέγξετε.

Endpoints διαχείρισης κλειδιών

Τα κλειδιά διαχειρίζονται μέσω του dashboard (Ρυθμίσεις → Κλειδιά API) ή του API:

Μέθοδος	Endpoint	Περιγραφή
GET	/api-keys/permissions	Λίστα όλων των εκχωρήσιμων scopes
POST	/api-keys	Δημιουργία κλειδιού (?environment=live ή test· σώμα: name, description?, permissions[], ipAllowlist?, expiresAt?) - η πλήρης τιμή του κλειδιού επιστρέφεται μία φορά
GET	/api-keys	Λίστα κλειδιών του χώρου εργασίας
GET	/api-keys/:apiKeyId	Λήψη των μεταδεδομένων ενός κλειδιού
PUT	/api-keys/:apiKeyId	Ενημέρωση ονόματος, περιγραφής, δικαιωμάτων, λίστας IP ή λήξης
POST	/api-keys/:apiKeyId/revoke	Απενεργοποίηση κλειδιού (σταματά αμέσως να πιστοποιείται)
POST	/api-keys/:apiKeyId/rotate	Δημιουργία νέας τιμής κλειδιού με διατήρηση των ίδιων δικαιωμάτων - η νέα τιμή επιστρέφεται μία φορά
DELETE	/api-keys/:apiKeyId	Οριστική διαγραφή κλειδιού (επιστρέφει 204)

Ένας καλών δεν μπορεί ποτέ να εκχωρήσει σε ένα κλειδί scopes που δεν κατέχει ο ίδιος.

Πεδία απόκρισης λίστας

Το GET /api-keys επιστρέφει { "apiKeys": [...] }, με κάθε κλειδί στην ακόλουθη μορφή (η πλήρης τιμή του κλειδιού και το hash της δεν εκτίθενται ποτέ):

{
  "apiKeys": [
    {
      "id": "7c2e4f6a-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "ServerSide Updates",
      "description": "Used by our backend to send events.",
      "keyPrefix": "jry_live_98f31a72",
      "permissions": ["events:track", "users:write"],
      "lastUsedAt": "2026-05-12T08:14:00.000Z",
      "expiresAt": null,
      "isActive": true,
      "createdAt": "2026-02-19T12:00:00.000Z",
      "updatedAt": "2026-02-19T12:00:00.000Z"
    }
  ]
}

Το ipAllowlist του κλειδιού ορίζεται κατά τη δημιουργία/ενημέρωση· επιβάλλεται σε κάθε αίτημα, αλλά δεν περιλαμβάνεται στην απόκριση της λίστας.

Συνήθη σφάλματα

Κατάσταση	Μήνυμα	Τι να ελέγξετε
401	Invalid API key format	Η κεφαλίδα λείπει, είναι κακοσχηματισμένη ή δεν ξεκινά με jry_.
401	Invalid or expired API key	Το κλειδί ανακλήθηκε, διαγράφηκε ή πέρασε το expiresAt του.
401	Request IP is not allowed for this API key	Η IP προέλευσης δεν ταίριαξε με καμία εγγραφή της λίστας - δείτε Λίστα επιτρεπόμενων IP.
403	This API key does not have the required permissions: ...	Το κλειδί είναι έγκυρο αλλά δεν έχει το scope που απαιτεί το endpoint.
403	ORG_HARD_SUSPENDED: organization is suspended. Read-only access only.	Ο οργανισμός-κάτοχος έχει ανασταλεί - επικοινωνήστε με την υποστήριξη.

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

Καλέστε POST /api-keys/:apiKeyId/rotate (ή χρησιμοποιήστε το dashboard): το κλειδί παίρνει νέα μυστική τιμή (και νέο keyPrefix) - που επιστρέφεται ακριβώς μία φορά στην απόκριση - διατηρώντας το όνομα, τα scopes και το ID του. Ό,τι εξακολουθεί να καλεί με την παλιά τιμή αρχίζει να αποτυγχάνει αμέσως, οπότε αναπτύξτε πρώτα τη νέα τιμή όπου μπορείτε και χρησιμοποιήστε το keyPrefix στα logs πρόσβασης για να βρείτε ενσωματώσεις που είναι ακόμη στο παλιό κλειδί. Αν προτιμάτε εναλλαγή χωρίς διακοπή λειτουργίας, δημιουργήστε δεύτερο κλειδί με τα ίδια scopes, μεταφέρετε τους καλούντες και έπειτα διαγράψτε το παλιό κλειδί.