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

Σχεδόν όλα τα αιτήματα προς το AstroWay API πιστοποιούνται μέσω του header X-Api-Key. Εξαιρέσεις: 14 endpoints /v1/reference/* (signs, planets, houses, aspects, …) λειτουργούν δημόσια χωρίς κλειδί με όριο 30 αιτήματα / ώρα ανά IP. Εάν τα αιτήματα γίνονται από τον διακομιστή σου, στείλε το header 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. Τα λεξικά αναφοράς /v1/reference/* - χωρίς κλειδί, δωρεάν (κανονικοί πίνακες αναζήτησης).

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

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: παραγωγή, αφαιρεί credits από το υπόλοιπο
aw_test_: sandbox, τα αιτήματα επιστρέφουν μια σταθερή απόκριση (ή έναν ελάχιστο πραγματικό υπολογισμό), δεν αφαιρούν credits, σημειώνονται ξεχωριστά στο dashboard
Μετά το πρόθεμα: 32 χαρακτήρες base62, κρυπτογραφικά τυχαίοι
Το κλειδί εμφανίζεται σε καθαρή μορφή μόνο μία φορά κατά τη δημιουργία. Στη συνέχεια, στο dashboard - μόνο οι πρώτοι και οι τελευταίοι 4 χαρακτήρες.

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

Postman collection

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

Published docs: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Public workspace: postman.com/astroway-info/astroway-api
Λήψη JSON: astroway-api.json (≈ 5 MB) - εισήγαγε απευθείας στο Postman ή το Insomnia

Η collection δημιουργείται αυτόματα από το 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: εάν ένα αίτημα με αυτό φέρει το header 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. Ένα κλειδί στον κώδικα της σελίδας μπορεί να διαβαστεί από οποιονδήποτε, οπότε δεν είναι ποτέ απεριόριστο. Μέχρι τις 12-09-2026, αυτή η λειτουργία σήμαινε “οποιαδήποτε προέλευση” (any origin). Στις 24-09-2026, τα τελευταία τέτοια κλειδιά έλαβαν μια λίστα που συλλέχθηκε από τη δική τους κίνηση, ή έγιναν server-side αν δεν είχαν αιτήματα browser. Η προέλευση από τη λίστα του κλειδιού 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. Environment variables, όχι 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: τοπική ανάπτυξη κάθε developer

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

4. Περιστροφή

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

Περιστροφή χωρίς downtime:

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

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

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

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

Σφάλματα πιστοποίησης

Κωδικός	Σημασία
`401 Unauthorized`	Το Header `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 req/min ανάλογα με το πλάνο)

Παράδειγμα 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 και όρια: πώς λειτουργεί η χρέωση και το rate limiting
Σφάλματα: πλήρης λίστα κωδικών σφαλμάτων

Χρήσιμο;

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

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

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

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

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

App templates