Autenticazione

Quasi tutte le richieste all’API AstroWay sono autenticate tramite l’header X-Api-Key. Eccezioni: 14 endpoint /v1/reference/* (signs, planets, houses, aspects, …) funzionano pubblicamente senza chiave con un limite di 30 richieste/ora per IP. Se le richieste sono effettuate dal tuo server, invia l’header X-AstroWay-Site-URL e il limite diventerà 300 richieste/ora per sito: dettagli.

Per tutti gli endpoint computazionali /v1/* (chart, synastry, transits, /reports, /tarot ecc.) - solo X-Api-Key. Per le operazioni utente /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, emesso tramite /v1/auth/login. OAuth/session-cookies non sono utilizzati sull’API pubblica. Dizionari di riferimento /v1/reference/* - senza chiave, gratuiti (tabelle di lookup canoniche).

Formato della chiave

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: produzione, scala crediti dal saldo
aw_test_: sandbox, le richieste restituiscono una risposta stub (o un calcolo reale minimo), non scalano crediti, contrassegnate separatamente nella dashboard
Dopo il prefisso: 32 caratteri base62, crittograficamente casuali
La chiave viene mostrata in chiaro solo una volta al momento della creazione. Successivamente nella dashboard - solo i primi e gli ultimi 4 caratteri.

Header della richiesta

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

Collezione Postman

Se per te è più comodo Postman rispetto a curl/SDK - c’è una collezione pronta con tutti gli 771 endpoint, suddivisa in 55 cartelle per tag OpenAPI, con esempi di richieste precompilati. L’autenticazione è configurata a livello di collezione: inserisci la chiave nella variabile apiKey una volta, e tutte le richieste la utilizzeranno.

Documentazione pubblicata: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Workspace pubblico: postman.com/astroway-info/astroway-api
Scarica JSON: astroway-api.json (≈ 5 MB) - importa direttamente in Postman o Insomnia

La collezione è auto-generata dallo spec OpenAPI - si aggiorna ad ogni deploy.

Creazione e gestione delle chiavi

Tramite dashboard:

api.astroway.info/dashboard/keys
Puoi avere fino a 10 chiavi attive per account contemporaneamente
Ogni chiave ha un nome, il campo name (ad esempio production-backend, ci-tests, local-dev)

Tramite API (per integrazioni 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

Chiavi per il browser

La chiave tipica è server-only: se una richiesta con essa porta l’header Origin o Referer, riceve 403 ORIGIN_FORBIDDEN. Questo è intenzionale, ed è ciò che intercetta una chiave lasciata accidentalmente nel frontend.

Quando un widget o una pagina devono accedere all’API dal browser, la chiave viene creata immediatamente con una politica di origine. Il campo origin_restriction in POST /v1/keys:

`tipo`	Cosa è permesso	Quando usare
`server-only` (predefinito)	solo richieste senza `Origin` e `Referer`	backend, cron, CI
`public`	solo gli host elencati, e la richiesta è obbligata a portare l’origine	widget o pagina sul tuo dominio, chiave nel codice sorgente
`allowlist`	lo stesso di `public`	scrittura obsoleta: è ancora accettato, ma non è più presente in `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/*"]
  }'

Regole di corrispondenza, testate in produzione:

Fino a 20 host per chiave. Lo schema (https://) e la porta vengono ignorati, il case non è rilevante.
www. viene rimosso dall’host in ingresso, quindi example.com copre anche www.example.com. Non è necessario aggiungere separatamente la forma con www., non cambia nulla.
*.example.com copre i sottodomini (app.example.com), ma non example.com stesso. L’apex è elencato su una riga separata, come nell’esempio sopra.
Un host non presente nell’elenco riceve 403 ORIGIN_NOT_ALLOWED con l’host stesso nel campo incoming_origin, in modo da mostrare quale riga manca.
Referer è considerato alla pari di Origin: il browser lo invia dove Origin non è presente.

type: "public" crea una chiave di classe pk_, e per essa la regola è inversa: una richiesta senza Origin e senza Referer riceve 403 ORIGIN_REQUIRED, e non passa come server-side. Pertanto, al momento della creazione sono obbligatorie tre cose: un elenco di domini, un budget credits_cap_cycle e un ambito allowed_endpoints (entrambi descritti di seguito). Senza uno di essi si riceve 400, e una chiave pk_ a cui manca il budget o l’ambito viene rifiutata ovunque con 403 PUBLISHABLE_KEY_UNBOUNDED. La chiave nel codice della pagina può essere letta da chiunque, quindi non è mai illimitata. Fino al 2026-09-12 questa modalità significava “qualsiasi origine”; il 2026-09-24 le ultime chiavi di questo tipo hanno ricevuto un elenco, raccolto dal loro stesso traffico, o sono diventate server-side se non avevano richieste browser. L’origine dall’elenco della chiave pk_ riceve anche access-control-allow-origin nelle risposte /v1/*, quindi la pagina può leggerle. La politica è visibile in GET /v1/keys nel campo origin_restriction.

Modificare l’elenco di una chiave già creata

PATCH /v1/keys/{id} sovrascrive l’elenco, senza toccare la chiave stessa. Il diritto di accesso è lo stesso di POST /v1/keys sopra; nella dashboard è la voce “Modifica origine” nel menu della chiave.

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"]
    }
  }'

Il nuovo elenco è attivo dalla richiesta successiva: la cache della chiave viene resettata durante la scrittura, non è necessario attendere un minuto. La stringa della chiave stessa non cambia, quindi non è necessario ripubblicare né la pagina né il backend. Dopo POST /v1/keys/{id}/rotate l’elenco viene mantenuto, e il vecchio valore della chiave smette di funzionare immediatamente.

La classe della chiave non è modificabile, perché è registrata nella chiave stessa:

Tentativo	Risposta
`pk_` rendere `server-only`	`400`: la classe fa parte della chiave, è necessario revocarla e crearne una nuova
`aw_` dare un elenco di domini	`400`: una chiave browser è di un’altra classe, viene creata come `public`
`pk_` con elenco vuoto	`400`: una chiave senza elenco rifiuterebbe ogni richiesta
`pk_` senza budget o ambito (`null`)	`400`: una chiave per il browser è sempre limitata da entrambi, possono essere modificati ma non rimossi

Budget di crediti per una singola chiave

I crediti sono condivisi per l’intero account, quindi una singola chiave può spenderli tutti. Per una chiave backend questo è normale, per una chiave nel codice sorgente di una pagina no: l’elenco dei domini dice da dove è possibile effettuare richieste, ma non dice quanto potrebbe costare.

credits_cap_cycle nello stesso PATCH /v1/keys/{id} limita specificamente questa chiave:

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 rimuove il limite (eccetto per la chiave pk_, per la quale il budget può essere modificato ma non rimosso). 0 significa una chiave con cui non si può spendere nulla: un modo per parcheggiare una chiave senza revocarla. Il contatore è lo stesso dei crediti e si azzera insieme al ciclo del piano tariffario.

Quando la chiave raggiunge il suo budget, si riceve 429 KEY_BUDGET_EXHAUSTED, anche se ci sono ancora crediti sull’account, e anche su un piano con overage: un budget che può essere superato a pagamento non è un budget. Finché il budget è impostato, ogni risposta porta X-Key-Budget-Limit e X-Key-Budget-Remaining.

Ambito degli endpoint

Una chiave senza ambito invoca tutto ciò che rientra nel piano tariffario. allowed_endpoints lo restringe a un elenco di percorsi: esatti (chart) o namespace (embed/*). Questa è la terza restrizione indipendente: l’elenco dei domini dice da dove, il budget quanto, l’ambito cosa esattamente.

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 rimuove il limite (eccetto per la chiave pk_, per la quale l’ambito è obbligatorio). Un elenco vuoto non è accettato: verrebbe interpretato sia come “tutto” che come “niente”. I percorsi sono scritti relativamente a /v1, senza lo slash iniziale, il case non è rilevante.

Una chiamata al di fuori dell’elenco riceve 403 ENDPOINT_NOT_IN_SCOPE, e details nomina l’elenco stesso, per evitare di dover indovinare. L’ambito si applica a entrambe le classi di chiavi e a /v1/public/* e /v1/embed/* allo stesso modo che al resto. Le letture di servizio da essa non sono esentate, a differenza dei crediti: una chiave ristretta a embed/* non leggerà nemmeno le proprie statistiche. Questo è intenzionale, perché una chiave nel codice sorgente della pagina non dovrebbe rivelare al visitatore le spese dell’account, e ciò non impedisce di gestire la chiave: la dashboard accede tramite sessione, non tramite chiave.

Best practice

1. Non inserire una chiave server-only nel frontend

Una chiave tipica è un segreto a livello di backend. Se finisce nel JS eseguito nel browser dell’utente - sarà visibile nei DevTools e verrà compromessa. È per questo che una tale chiave risponde con 403 ORIGIN_FORBIDDEN a qualsiasi richiesta con Origin o Referer.

Se è comunque necessario accedere dal browser, questo non si fa con una chiave normale, ma con una separata, creata con origin_restriction.type: "public": chiavi per il browser. Una tale chiave ha il prefisso pk_, è anch’essa visibile nei DevTools, e questo è il punto: il suo valore è limitato all’elenco dei tuoi domini, e rifiuta una richiesta senza origine.

Corretto: il tuo backend detiene la chiave, il frontend chiama il tuo backend, il tuo backend chiama l’API AstroWay.

Sbagliato:

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

2. Variabili d’ambiente, non 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. Chiavi separate per ambienti diversi

production-backend: produzione
staging-backend: staging
ci-tests: pipeline CI/CD
local-dev-maksym: sviluppo locale di ogni sviluppatore

Se una chiave è compromessa - revoca solo quella, le altre continuano a funzionare.

4. Rotazione

Frequenza raccomandata - una volta ogni 90 giorni. O immediatamente, se c’è il sospetto di una fuga.

Rotazione senza downtime:

Crea una nuova chiave con lo stesso name + -v2
Distribuiscila in produzione (parallelamente alla vecchia)
Assicurati che l’utilizzo si sposti sulla nuova chiave (dashboard)
Revoca la vecchia

5. Monitoraggio dell’utilizzo

La dashboard mostra le richieste per chiave separatamente. Se improvvisamente una chiave inizia a fare 10× più richieste del solito - è un segnale da controllare.

Puoi impostare un alert: Settings → Notifications → Alert when daily credits > X.

Errori di autenticazione

Codice	Significato
`401 Unauthorized`	Header `X-Api-Key` assente o chiave non valida
`403 Forbidden`	Chiave valida, ma non ha l’ambito per questa azione (ad esempio, una chiave normale tenta di gestire altre chiavi)
`403 PUBLISHABLE_KEY_UNBOUNDED`	Chiave `pk_` senza budget `credits_cap_cycle` o senza ambito `allowed_endpoints`: imposta entrambi nelle impostazioni della chiave
`402 Payment Required`	Crediti esauriti (su Free) o abbonamento inattivo
`429 Too Many Requests`	Limite di rate superato (10/60/300 req/min a seconda del piano)

Esempio 401:

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

Modalità Sandbox

Le chiavi con prefisso aw_test_ funzionano in sandbox:

Non scalano crediti
Restituiscono una risposta stub o un calcolo reale minimo
Non influenzano le statistiche di produzione
Endpoint disponibili: gli stessi

Utile per CI/CD, test e2e e sviluppo locale. Si crea tramite dashboard con un solo clic.

Prossimi passi

Crediti e limiti: come funzionano la fatturazione e il rate limiting
Errori: elenco completo dei codici di errore

Utile?

Suggerisci modifica

Ultimo aggiornamento: 5 ott 2026