Autentificare

Aproape toate cererile către AstroWay API sunt autentificate prin header X-Api-Key. Excepții: 14 endpointuri /v1/reference/* (signs, planets, houses, aspects, …) funcționează public fără cheie, cu limita de 30 de cereri / oră pe IP. Dacă cererile le face serverul tău, trimite headerul X-AstroWay-Site-URL și limita devine 300 de cereri / oră pe site: detalii.

Obține cheia API în 60 de secunde

aw_test_demo_aaaa1111

Înregistrează-te - gratuit→

Pentru toate endpointurile de calcul /v1/* (chart, synastry, transits, /reports, /tarot etc.) - doar X-Api-Key. Pentru operații de utilizator /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, emis prin /v1/auth/login. OAuth/session-cookies nu sunt folosite pe API-ul public. Dicționarele de referință /v1/reference/* - fără cheie, gratuit (tabele de căutare canonice).

Formatul cheii

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

• aw_live_: production, scade credite din sold
• aw_test_: sandbox, cererile returnează un răspuns stabil (sau un calcul real minim), nu scad credite, marcate separat în dashboard
• După prefix: 32 de caractere base62, criptografic aleatorii
• Cheia este afișată în formă curată doar o singură dată la creare. După aceea în dashboard - doar primele și ultimele 4 caractere.

Headerul cererii

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

Colecție Postman

Dacă ți se pare mai convenabil Postman decât curl/SDK - există o colecție gata cu toate 771 endpointuri, împărțită în 55 de directoare pe taguri OpenAPI, cu exemple de cereri inserate. Auth este configurat la nivel de colecție: introduci cheia în variabila apiKey o singură dată, toate cererile o preiau.

• Documentație publicată: documenter.getpostman.com/view/54689779/2sBXqNmy3n
• Spațiu de lucru public: postman.com/astroway-info/astroway-api
• Descarcă JSON: astroway-api.json (≈ 5 MB) - importă direct în Postman sau Insomnia

Colecția este auto-generată din OpenAPI spec - se actualizează la fiecare deploy.

Crearea și gestionarea cheilor

Prin dashboard:

• https://api.astroway.info/dashboard/keys
• Poți avea până la 10 chei active pe cont simultan
• Fiecare cheie are un nume, câmpul name (de exemplu production-backend, ci-tests, local-dev)

Prin API (pentru integrări self-service):

cURL

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

TypeScript

// 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

Python

# 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

<?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

Sfat

Cheia master (cea pe care ai creat-o în dashboard) poate gestiona alte chei prin /v1/keys. Cheile obișnuite - nu pot. Acest lucru este specificat în scope cheii.

Chei pentru browser

Cheia tipică server-only: dacă o cerere cu ea conține headerul Origin sau Referer, primește 403 ORIGIN_FORBIDDEN. Este intenționat, și este ceea ce prinde cheia, lăsată accidental în frontend.

Când widgetul sau pagina trebuie să acceseze API-ul din browser, cheia este creată imediat cu o politică de origine. Câmpul origin_restriction în POST /v1/keys:

type	Ce este permis	Când să folosești
server-only (implicit)	doar cereri fără Origin și Referer	backend, cron, CI
public	doar gazdele enumerate, și cererea trebuie să conțină origine	widget sau pagină pe domeniul tău, cheia în codul sursă
allowlist	același ca public	scriere învechită: încă acceptată, dar nu mai apare în 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/*"]
  }'

Reguli de potrivire, verificate în producție:

• Până la 20 gazde pe cheie. Schema (https://) și portul sunt ignorate, cazul nu contează.
• www. este eliminat din gazda de intrare, astfel example.com acoperă și www.example.com. Nu este nevoie să adaugi separat forma cu www., nu schimbă nimic.
• *.example.com acoperă subdomeniile (app.example.com), dar nu example.com în sine. Asteriscul este listat pe o linie separată, ca în exemplul de mai sus.
• O gazdă care nu este în listă primește 403 ORIGIN_NOT_ALLOWED cu gazda respectivă în câmpul incoming_origin, pentru a vedea ce linie lipsește.
• Referer este tratat la fel ca Origin: browserul îl trimite acolo unde Origin lipsește.

Atenție

type: "public" creează o cheie de clasa pk_, și pentru ea regula este inversă: o cerere fără Origin și fără Referer primește 403 ORIGIN_REQUIRED, și nu este tratată ca server. Prin urmare, la creare sunt obligatorii trei lucruri: lista de domenii, bugetul credits_cap_cycle și zona allowed_endpoints (ambele descrise mai jos). Fără oricare dintre ele primești 400, iar cheia pk_, căreia îi lipsește bugetul sau zona, este respinsă peste tot cu 403 PUBLISHABLE_KEY_UNBOUNDED. Cheia în codul paginii poate fi citită de oricine, deci nu este niciodată nelimitată. Până pe 2026-09-12 acest mod însemna “orice origin”; pe 2026-09-24 ultimele astfel de chei au primit o listă, adunată din traficul lor, sau au devenit server, dacă nu existau cereri din browser. Origin din lista cheii pk_ primește de asemenea access-control-allow-origin în răspunsurile /v1/*, astfel pagina le poate citi. Politica este vizibilă în GET /v1/keys în câmpul origin_restriction.

Modifică lista la o cheie deja creată

PATCH /v1/keys/{id} rescrie lista, fără a atinge cheia însăși. Dreptul de acces este același ca la POST /v1/keys de mai sus; în dashboard este opțiunea “Modifică origine” în meniul cheii.

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

Noua listă intră în vigoare de la următoarea cerere: cache-ul cheii este resetat în timpul scrierii, nu trebuie să aștepți un minut. Șirul cheii în sine nu se schimbă, deci nu e nevoie să re-deployezi nici pagina, nici backend-ul. După POST /v1/keys/{id}/rotate lista este păstrată, iar valoarea veche a cheii încetează să funcționeze imediat.

Clasa cheii nu poate fi editată, deoarece este încorporată în cheie:

Încercare	Răspuns
pk_ să devină server-only	400: clasa face parte din cheie, trebuie revocat și creat unul nou
aw_ să aibă listă de domenii	400: cheia de browser este altă clasă, se creează ca public
pk_ cu listă goală	400: o cheie fără listă ar respinge fiecare cerere
pk_ fără buget sau zonă (null)	400: cheia pentru browser este întotdeauna limitată de ambele, pot fi modificate, dar nu eliminate

Buget de credite pentru o cheie individuală

Creditele sunt comune pentru întregul cont, așa că o cheie poate consuma toate. Pentru o cheie de backend e normal, pentru o cheie în codul sursă al paginii nu: lista de domenii spune de unde se poate accesa, dar nu spune cât poate costa.

credits_cap_cycle în același PATCH /v1/keys/{id} limitează exact această cheie:

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 elimină limita (cu excepția cheii pk_, al cărei buget poate fi modificat, dar nu eliminat). 0 înseamnă o cheie cu care nu poți cheltui nimic: o metodă de a parca cheia fără a o revoca. Contorul este același ca al creditelor și se resetează odată cu ciclul tarifar.

Când cheia atinge bugetul său, primește 429 KEY_BUDGET_EXHAUSTED, chiar dacă în cont mai sunt credite, și chiar și pe un plan cu overage: bugetul care poate fi depășit contra cost nu este buget. Atâta timp cât bugetul este setat, fiecare răspuns conține X-Key-Budget-Limit și X-Key-Budget-Remaining.

Domeniul endpointurilor

O cheie fără zonă poate accesa tot ce este inclus în plan. allowed_endpoints o restrânge la o listă de căi: exacte (chart) sau spațiu de nume (embed/*). Aceasta este a treia limitare independentă: lista de domenii spune de unde, bugetul spune cât, zona spune ce anume.

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 elimină limita (cu excepția cheii pk_, al cărei domeniu este obligatoriu). O listă goală nu este acceptată: ar fi citită atât ca “tot”, cât și ca “nimic”. Căile se scriu relativ la /v1, fără slash inițial, cazul valorii nu contează.

O cerere în afara listei primește 403 ENDPOINT_NOT_IN_SCOPE, iar details indică lista însăși, pentru a nu trebui să ghicești. Domeniul se aplică ambelor clase de chei și la /v1/public/* și la /v1/embed/* la fel ca la restul. Citirile de serviciu sub el nu sunt scutite, spre deosebire de credite: o cheie restrânsă la embed/* nu va citi nici statisticile proprii. Este intenționat, deoarece o cheie în codul sursă al paginii nu ar trebui să expună vizitatorului cheltuielile contului, iar gestionarea cheii nu interferează: dashboard-ul funcționează cu sesiunea, nu cu cheia.

Cele mai bune practici

1. Nu pune cheia server-only în frontend

Cheia tipică este un secret la nivel de backend. Dacă ajunge în JS care rulează în browserul utilizatorului - este vizibilă în DevTools și se va scurge. De aceea o astfel de cheie răspunde cu 403 ORIGIN_FORBIDDEN la orice cerere cu Origin sau Referer.

Dacă trebuie să accesezi din browser, se face cu o cheie separată, creată cu origin_restriction.type: "public": chei pentru browser. O astfel de cheie are prefixul pk_, este de asemenea vizibilă în DevTools, și asta e esența - valoarea ei este limitată la lista domeniilor tale, iar o cerere fără origine este respinsă.

Corect: backend-ul tău păstrează cheia, frontend-ul se conectează la backend-ul tău, backend-ul tău - la AstroWay API.

Greșit:

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

2. Variabile de mediu, nu 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. Chei separate pentru diferite medii

• production-backend: producție
• staging-backend: staging
• ci-tests: pipeline CI/CD
• local-dev-maksym: dezvoltare locală a fiecărui dezvoltator

Dacă o cheie este compromisă - revocă exact acea cheie, celelalte continuă să funcționeze.

4. Rotire

Frecvența recomandată - o dată la 90 de zile. Sau imediat, dacă există suspiciunea unei scurgeri.

1. Creează o cheie nouă cu același name + -v2
2. Deplaseaz-o în producție (paralel cu cea veche)
3. Asigură-te că utilizarea curge către noua cheie (dashboard)
4. Revocă cea veche

5. Monitorizarea utilizării

Dashboard-ul arată cererile pe chei separat. Dacă brusc o cheie începe să facă de 10× mai multe cereri decât de obicei - este un semnal să verifici.

Poți seta un alert: Settings → Notifications → Alert when daily credits > X.

Erori de autentificare

Cod	Valoare
401 Unauthorized	Header X-Api-Key lipsește sau cheia este nevalidă
403 Forbidden	Cheia este validă, dar nu are scope pentru această acțiune (de exemplu, o cheie obișnuită încearcă să gestioneze alte chei)
403 PUBLISHABLE_KEY_UNBOUNDED	Cheia pk_ fără buget credits_cap_cycle sau fără zonă allowed_endpoints: setează ambele în setările cheii
402 Payment Required	Creditele s-au epuizat (pe Free) sau abonamentul este inactiv
429 Too Many Requests	Depășit rate limit (10/60/300 req/min în funcție de plan)

Exemplu 401:

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

Mod sandbox

Cheile cu prefixul aw_test_ funcționează în sandbox:

• Nu scad credite
• Returnează un răspuns stabil sau un calcul real minim
• Nu afectează statistica de producție
• Endpointuri disponibile: aceleași

Util pentru CI/CD, teste e2e și dezvoltare locală. Se creează prin dashboard cu un singur click.

În continuare

• Credite și limite: cum funcționează billing-ul și rate limiting
• Erori: listă completă a codurilor de eroare