Αυθεντικοποίηση

Σχεδόν όλα τα αιτήματα προς το AstroWay API επαληθεύονται μέσω της κεφαλίδας X-Api-Key. Εξαιρέσεις: 14 endpoints /v1/reference/* (signs, planets, houses, aspects, …) λειτουργούν δημόσια χωρίς κλειδί με όριο 30 αιτημάτων / ώρα ανά IP. Αν τα αιτήματα γίνονται από τον διακομιστή σου, στείλε την κεφαλίδα X-AstroWay-Site-URL και το όριο θα γίνει 300 αιτήματα / ώρα ανά ιστότοπο: λεπτομέρειες.

Για όλα τα υπολογιστικά endpoints /v1/* (chart, synastry, transits, /reports, /tarot κ.λπ.) - μόνο X-Api-Key. Για λειτουργίες χρήστη /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, εκδίδεται μέσω /v1/auth/login. OAuth/session-cookies δεν χρησιμοποιούνται στο δημόσιο API. Reference-λεξικά /v1/reference/* - χωρίς κλειδί, δωρεάν (κανονικοί πίνακες αναζήτησης).

Μορφή κλειδιού

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: παραγωγή, χρεώνει credits από το υπόλοιπο
aw_test_: sandbox, τα αιτήματα επιστρέφουν μια σταθερή απόκριση (ή έναν ελάχιστο πραγματικό υπολογισμό), δεν χρεώνουν credits, σημειώνονται ξεχωριστά στο dashboard
Μετά το πρόθεμα: 48 δεκαεξαδικά σύμβολα, κρυπτογραφικά τυχαία
Το κλειδί εμφανίζεται σε καθαρή μορφή μόνο μία φορά: κατά τη δημιουργία ή την ενημέρωση. Αποθηκεύουμε μόνο το SHA-256 του, οπότε δεν είναι δυνατή η εκ νέου εμφάνιση του κλειδιού, μπορεί μόνο να ανανεωθεί. Στη συνέχεια, στο dashboard είναι ορατό μόνο το πρόθεμα και οι τελευταίοι 4 χαρακτήρες.
Ένα κλειδί που δημιουργήθηκε κατά τη σύνδεση μέσω Google, GitHub, εφάπαξ κωδικού ή από μια παραγγελία, δεν έχει δει κανείς ακόμα. Στο dashboard, δίπλα του υπάρχει ένα κουμπί “Εμφάνιση κλειδιού”: εκδίδει ένα νέο κλειδί της ίδιας κλάσης μία φορά.

Κεφαλίδα αιτήματος

POST /v1/chart HTTP/1.1
Host: api.astroway.info
X-Api-Key: aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
Content-Type: application/json

Συλλογή Postman

Αν το Postman είναι πιο βολικό για εσένα από το curl/SDK - υπάρχει μια έτοιμη συλλογή με όλα τα 771 endpoints, αναδιαρθρωμένη σε 55 φακέλους ανά OpenAPI tags, με προ-συμπληρωμένα παραδείγματα αιτημάτων. Ο έλεγχος ταυτότητας έχει ρυθμιστεί σε επίπεδο συλλογής: εισάγεις το κλειδί στην μεταβλητή apiKey μία φορά, και όλα τα αιτήματα το χρησιμοποιούν.

Δημοσιευμένη τεκμηρίωση: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Δημόσιος χώρος εργασίας: postman.com/astroway-info/astroway-api
Λήψη JSON: astroway-api.json (≈ 5 MB) - εισάγετε απευθείας στο Postman ή το Insomnia

Η συλλογή δημιουργείται αυτόματα από το OpenAPI spec - ενημερώνεται με κάθε deployment.

Δημιουργία και διαχείριση κλειδιών

Μέσω dashboard:

api.astroway.info/dashboard/keys
Μπορείς να έχεις έως και 10 ενεργά κλειδιά ανά λογαριασμό ταυτόχρονα
Κάθε κλειδί έχει ένα όνομα, το πεδίο name (π.χ. production-backend, ci-tests, local-dev)

Μέσω API (για self-service ενσωματώσεις):

curl -X POST https://api.astroway.info/v1/keys \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-tests", "mode": "test"}'

// Equivalent via @astroway/sdk: aw.client.POST('/keys', { body: { name, mode } })
const r = await fetch('https://api.astroway.info/v1/keys', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_MASTER_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'ci-tests', mode: 'test' }),
});

const { data: created } = await r.json();
console.log(created.api_key); // shown once - store it now

# Equivalent via `astroway` (PyPI): aw.post('/keys', body={'name': ..., 'mode': ...})
import os, requests

r = requests.post(
    'https://api.astroway.info/v1/keys',
    headers={'X-Api-Key': os.environ['ASTROWAY_MASTER_KEY']},
    json={'name': 'ci-tests', 'mode': 'test'},
)
created = r.json()['data']
print(created['api_key'])  # shown once - store it now

<?php
use GuzzleHttp\Client;

$aw = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
$r = $aw->post('keys', [
    'headers' => ['X-Api-Key' => getenv('ASTROWAY_MASTER_KEY')],
    'json' => ['name' => 'ci-tests', 'mode' => 'test'],
]);

$created = json_decode($r->getBody(), true)['data'];
echo $created['api_key']; // shown once - store it now

Κλειδιά για browser

Το τυπικό κλειδί είναι server-only: αν ένα αίτημα με αυτό φέρει την κεφαλίδα Origin ή Referer, επιστρέφεται 403 ORIGIN_FORBIDDEN. Αυτό είναι σκόπιμο, και αυτό είναι που πιάνει ένα κλειδί που έχει μείνει κατά λάθος στο frontend.

Όταν ένα widget ή μια σελίδα πρέπει να καλεί το API από τον browser, το κλειδί δημιουργείται αμέσως με πολιτική προέλευσης. Το πεδίο origin_restriction στο POST /v1/keys:

`type`	Τι επιτρέπεται	Πότε να χρησιμοποιείται
`server-only` (προεπιλογή)	μόνο αιτήματα χωρίς `Origin` και `Referer`	backend, cron, CI
`public`	μόνο οι αναφερόμενοι hosts, και το αίτημα είναι υποχρεωτικό να φέρει προέλευση	widget ή σελίδα στον τομέα σου, κλειδί στον πηγαίο κώδικα
`allowlist`	το ίδιο με το `public`	παρωχημένη γραφή: εξακολουθεί να γίνεται δεκτή, αλλά δεν αναφέρεται πλέον στο `openapi.json`

curl -X POST https://api.astroway.info/v1/keys \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "site-widget",
    "origin_restriction": {
      "type": "public",
      "allowed_origins": ["example.com", "*.example.com"]
    },
    "credits_cap_cycle": 20000,
    "allowed_endpoints": ["chart", "public/*"]
  }'

Κανόνες αντιστοίχισης, δοκιμασμένοι σε παραγωγή:

Έως 20 hosts ανά κλειδί. Το σχήμα (https://) και η θύρα αγνοούνται, η διάκριση πεζών-κεφαλαίων δεν έχει σημασία.
Το www. αφαιρείται από τον εισερχόμενο host, οπότε το example.com καλύπτει και το www.example.com. Δεν χρειάζεται να προσθέσετε ξεχωριστά τη μορφή με www., δεν αλλάζει τίποτα.
Το *.example.com καλύπτει υποτομείς (app.example.com), αλλά όχι το ίδιο example.com. Το apex αναφέρεται σε ξεχωριστή γραμμή, όπως στο παραπάνω παράδειγμα.
Ένας host που δεν είναι στη λίστα λαμβάνει 403 ORIGIN_NOT_ALLOWED με τον ίδιο τον host στο πεδίο incoming_origin, ώστε να είναι ορατή η γραμμή που λείπει.
Το Referer υπολογίζεται ισότιμα με το Origin: ο browser το στέλνει όταν δεν υπάρχει Origin.

Το type: "public" δημιουργεί ένα κλειδί της κλάσης pk_, και για αυτό ο κανόνας είναι αντίστροφος: ένα αίτημα χωρίς Origin και χωρίς Referer λαμβάνει 403 ORIGIN_REQUIRED, αντί να περάσει ως server-side. Επομένως, κατά τη δημιουργία, τρία πράγματα είναι υποχρεωτικά: η λίστα τομέων, ο προϋπολογισμός credits_cap_cycle και το πεδίο allowed_endpoints (και τα δύο περιγράφονται παρακάτω). Χωρίς κάποιο από αυτά, επιστρέφεται 400, και ένα κλειδί pk_ που στερείται προϋπολογισμού ή πεδίου απορρίπτεται παντού με 403 PUBLISHABLE_KEY_UNBOUNDED. Το κλειδί στον κώδικα της σελίδας μπορεί να διαβαστεί από οποιονδήποτε, οπότε δεν είναι ποτέ απεριόριστο. Μέχρι τις 2026-09-12, αυτή η λειτουργία σήμαινε “οποιαδήποτε προέλευση”· στις 2026-09-24, τα τελευταία τέτοια κλειδιά έλαβαν μια λίστα, συλλεγμένη από τη δική τους κίνηση, ή έγιναν server-side, αν δεν είχαν αιτήματα browser. Το Origin από τη λίστα του κλειδιού pk_ λαμβάνει επίσης access-control-allow-origin στις απαντήσεις /v1/*, οπότε η σελίδα μπορεί να τα διαβάσει. Η πολιτική είναι ορατή στο GET /v1/keys στο πεδίο origin_restriction.

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

Το PATCH /v1/keys/{id} αντικαθιστά τη λίστα, χωρίς να αγγίζει το ίδιο το κλειδί. Το δικαίωμα πρόσβασης είναι το ίδιο με το POST /v1/keys παραπάνω· στο dashboard αυτό είναι το στοιχείο “Αλλαγή προέλευσης” στο μενού του κλειδιού.

curl -X PATCH https://api.astroway.info/v1/keys/433 \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_restriction": {
      "type": "public",
      "allowed_origins": ["example.com", "*.example.com"]
    }
  }'

Η νέα λίστα ισχύει από το επόμενο αίτημα: η cache του κλειδιού εκκαθαρίζεται κατά την εγγραφή, δεν χρειάζεται να περιμένετε ένα λεπτό. Η ίδια η συμβολοσειρά του κλειδιού δεν αλλάζει, οπότε ούτε η σελίδα ούτε το backend χρειάζεται να επανεκδοθούν. Μετά το POST /v1/keys/{id}/rotate, η λίστα διατηρείται, και η παλιά τιμή του κλειδιού παύει να λειτουργεί αμέσως.

Η κλάση του κλειδιού δεν επεξεργάζεται, γιατί είναι γραμμένη στο ίδιο το κλειδί:

Προσπάθεια	Απόκριση
Να γίνει το `pk_` `server-only`	`400`: η κλάση είναι μέρος του κλειδιού, πρέπει να ανακληθεί και να δημιουργηθεί νέο
Να δοθεί στο `aw_` μια λίστα τομέων	`400`: ένα κλειδί browser είναι διαφορετική κλάση, δημιουργείται ως `public`
`pk_` με κενή λίστα	`400`: ένα κλειδί χωρίς λίστα θα απέρριπτε κάθε αίτημα
`pk_` χωρίς προϋπολογισμό ή πεδίο (`null`)	`400`: ένα κλειδί για browser είναι πάντα περιορισμένο και από τα δύο, μπορούν να αλλάξουν, αλλά όχι να αφαιρεθούν

Προϋπολογισμός credits ανά ξεχωριστό κλειδί

Τα credits είναι κοινά για όλο τον λογαριασμό, οπότε ένα κλειδί μπορεί να τα ξοδέψει όλα. Για ένα backend-κλειδί αυτό είναι φυσιολογικό, για ένα κλειδί στον πηγαίο κώδικα της σελίδας όχι: η λίστα τομέων λέει από πού μπορείς να κάνεις αιτήματα, αλλά δεν λέει πόσο μπορεί να κοστίσει.

Το credits_cap_cycle στο ίδιο PATCH /v1/keys/{id} περιορίζει αυτό το συγκεκριμένο κλειδί:

curl -X PATCH https://api.astroway.info/v1/keys/433 \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"credits_cap_cycle": 5000}'

Το null αφαιρεί τον περιορισμό (εκτός από το κλειδί pk_, για το οποίο ο προϋπολογισμός μπορεί να αλλάξει, αλλά όχι να αφαιρεθεί). Το 0 σημαίνει ένα κλειδί που δεν μπορεί να ξοδέψει τίποτα: ένας τρόπος να “παρκάρεις” ένα κλειδί, χωρίς να το ανακαλέσεις. Ο μετρητής είναι ο ίδιος με αυτόν των credits, και μηδενίζεται μαζί με τον κύκλο του πακέτου.

Όταν ένα κλειδί φτάσει το όριο του προϋπολογισμού του, επιστρέφεται 429 KEY_BUDGET_EXHAUSTED, ακόμα κι αν υπάρχουν ακόμα credits στον λογαριασμό, και ακόμα και σε πακέτο με overage: ένας προϋπολογισμός που μπορεί να υπερβεί με χρήματα, δεν είναι προϋπολογισμός. Όσο ο προϋπολογισμός είναι καθορισμένος, κάθε απάντηση φέρει X-Key-Budget-Limit και X-Key-Budget-Remaining.

Πεδίο εφαρμογής endpoints

Ένα κλειδί χωρίς πεδίο εφαρμογής καλεί οτιδήποτε περιλαμβάνεται στο πακέτο. Το allowed_endpoints το περιορίζει σε μια λίστα διαδρομών: ακριβών (chart) ή χώρου ονομάτων (embed/*). Αυτός είναι ο τρίτος, ανεξάρτητος περιορισμός: η λίστα τομέων λέει από πού, ο προϋπολογισμός πόσο, το πεδίο εφαρμογής τι ακριβώς.

curl -X PATCH https://api.astroway.info/v1/keys/433 \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"allowed_endpoints": ["embed/*", "public/moon-phase"]}'

Το null αφαιρεί τον περιορισμό (εκτός από το κλειδί pk_, για το οποίο το πεδίο εφαρμογής είναι υποχρεωτικό). Μια κενή λίστα δεν γίνεται δεκτή: θα διαβαζόταν εξίσου ως “όλα” και ως “τίποτα”. Οι διαδρομές γράφονται σε σχέση με το /v1, χωρίς αρχική κάθετο, η διάκριση πεζών-κεφαλαίων δεν έχει σημασία.

Μια κλήση εκτός λίστας λαμβάνει 403 ENDPOINT_NOT_IN_SCOPE, και τα details αναφέρουν την ίδια τη λίστα, ώστε να μην χρειάζεται να μαντέψετε. Το πεδίο εφαρμογής ισχύει και για τις δύο κλάσεις κλειδιών και για τα /v1/public/* και /v1/embed/*, όπως και για τα υπόλοιπα. Οι υπηρεσιακές αναγνώσεις από κάτω της δεν εξαιρούνται, σε αντίθεση με τα credits: ένα κλειδί, περιορισμένο στο embed/*, δεν θα διαβάσει ούτε τα δικά του στατιστικά. Αυτό είναι σκόπιμο, γιατί ένα κλειδί στον πηγαίο κώδικα της σελίδας δεν πρέπει να αποκαλύπτει στον επισκέπτη τα έξοδα του λογαριασμού, και αυτό δεν εμποδίζει τη διαχείριση του κλειδιού: το dashboard χρησιμοποιεί session, όχι κλειδί.

Βέλτιστες πρακτικές

1. Μην τοποθετείς server-only κλειδί στο frontend

Το τυπικό κλειδί είναι ένα μυστικό σε επίπεδο backend. Αν καταλήξει σε JS που εκτελείται στον browser του χρήστη - είναι ορατό στα DevTools και θα διαρρεύσει. Γι’ αυτό ακριβώς ένα τέτοιο κλειδί απαντά με 403 ORIGIN_FORBIDDEN σε οποιοδήποτε αίτημα με Origin ή Referer.

Αν παρόλα αυτά πρέπει να γίνει κλήση από τον browser, αυτό γίνεται όχι με ένα συνηθισμένο κλειδί, αλλά με ένα ξεχωριστό, δημιουργημένο με origin_restriction.type: "public": κλειδιά για browser. Ένα τέτοιο κλειδί έχει το πρόθεμα pk_, είναι επίσης ορατό στα DevTools, και αυτή είναι όλη η ουσία - η αξία του περιορίζεται από τη λίστα των τομέων σου, και απορρίπτει ένα αίτημα χωρίς προέλευση.

Σωστό: το backend σου κρατά το κλειδί, το frontend καλεί το backend σου, το backend σου - το AstroWay API.

Λάθος:

// DO NOT DO THIS
fetch('https://api.astroway.info/v1/chart', {
  headers: { 'X-Api-Key': 'aw_live_...' }, // visible in browser
});

2. Μεταβλητές περιβάλλοντος, όχι hardcode

# .env (in .gitignore)
ASTROWAY_API_KEY=aw_live_...

// in code
const key = process.env.ASTROWAY_API_KEY;
if (!key) throw new Error('ASTROWAY_API_KEY is not set');

3. Ξεχωριστά κλειδιά για διαφορετικά περιβάλλοντα

production-backend: παραγωγή
staging-backend: staging
ci-tests: CI/CD pipeline
local-dev-maksym: τοπική ανάπτυξη κάθε προγραμματιστή

Αν ένα κλειδί έχει παραβιαστεί - ανάκλησε μόνο αυτό, τα άλλα συνεχίζουν να λειτουργούν.

4. Ανανέωση

Συνιστώμενη συχνότητα - μία φορά κάθε 90 ημέρες. Ή αμέσως, αν υπάρχει υποψία διαρροής.

Ανανέωση χωρίς downtime:

Δημιούργησε ένα νέο κλειδί με το ίδιο name + -v2
Ανάπτυξέ το στην παραγωγή (παράλληλα με το παλιό)
Βεβαιώσου ότι η χρήση μεταφέρεται στο νέο κλειδί (dashboard)
Ανάκλησε το παλιό

5. Παρακολούθηση χρήσης

Το Dashboard δείχνει τα αιτήματα ανά κλειδί ξεχωριστά. Αν ξαφνικά ένα κλειδί άρχισε να κάνει 10× περισσότερα αιτήματα από το συνηθισμένο - αυτό είναι ένα σήμα για έλεγχο.

Μπορείς να ρυθμίσεις μια ειδοποίηση: Settings → Notifications → Alert when daily credits > X.

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

Κωδικός	Σημασία
`401 Unauthorized`	Η κεφαλίδα `X-Api-Key` λείπει ή το κλειδί δεν είναι έγκυρο
`403 Forbidden`	Το κλειδί είναι έγκυρο, αλλά δεν έχει το κατάλληλο scope για αυτήν την ενέργεια (π.χ., ένα κανονικό κλειδί προσπαθεί να διαχειριστεί άλλα κλειδιά)
`403 PUBLISHABLE_KEY_UNBOUNDED`	Κλειδί `pk_` χωρίς προϋπολογισμό `credits_cap_cycle` ή χωρίς πεδίο `allowed_endpoints`: ορίστε και τα δύο στις ρυθμίσεις του κλειδιού
`402 Payment Required`	Τα credits τελείωσαν (στο Free) ή η συνδρομή δεν είναι ενεργή
`429 Too Many Requests`	Έχει ξεπεραστεί το όριο ρυθμού (rate limit) (10/60/300 αιτήματα/λεπτό ανάλογα με το πακέτο)

Παράδειγμα 401:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "8aec43e9bc749b37e998a489bbad1757"
  }
}

Λειτουργία Sandbox

Τα κλειδιά με πρόθεμα aw_test_ λειτουργούν σε sandbox:

Δεν χρεώνουν credits
Επιστρέφουν μια σταθερή ή ελάχιστη πραγματική απόκριση
Δεν επηρεάζουν τα στατιστικά παραγωγής
Διαθέσιμα endpoints: τα ίδια

Χρήσιμο για CI/CD, e2e tests και τοπική ανάπτυξη. Δημιουργείται μέσω του dashboard με ένα κλικ.

Στη συνέχεια

Credits και όρια: πώς λειτουργεί η χρέωση και ο περιορισμός ρυθμού
Σφάλματα: πλήρης κατάλογος κωδικών σφαλμάτων

Χρήσιμο;

Προτείνετε διόρθωση

Τελευταία ενημέρωση: 16 Οκτ 2026

// Προηγούμενη σελίδα

Γρήγορη έναρξη

Επόμενη σελίδα //

App templates