Hitelesítés

Majdnem minden kérés az AstroWay API-hoz a X-Api-Key fejlécen keresztül hitelesített. Kivételek: 14 végpont /v1/reference/* (signs, planets, houses, aspects, …) nyilvánosan működnek kulcs nélkül, IP-nként 30 kérés/óra korláttal. Ha a szervered küldi a kéréseket, küldd el a X-AstroWay-Site-URL fejlécet, és a limit 300 kérés/óra lesz a weboldalra: részletek.

Minden számítási végponthoz /v1/* (chart, synastry, transits, /reports, /tarot stb.) – csak X-Api-Key. Felhasználói műveletekhez /v1/me/* (GET /me, DELETE /me/account) – Bearer JWT, amely a /v1/auth/login-on keresztül kapott. OAuth/session-cookies a nyilvános API-n nem használatos. Reference-szótárak /v1/reference/* – kulcs nélkül, ingyen (kanonikus lookup-táblák).

Kulcs formátuma

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: production, levon krediteket a egyenlegből
aw_test_: sandbox, a kérések stabil választ adnak (vagy minimális valós számítást), nem vonnak le krediteket, a dashboardon külön jelölve
A prefix után: 32 karakter base62, kriptográfiailag véletlenszerű
A kulcs tiszta formában csak egyszer jelenik meg a létrehozáskor. Később a dashboardon csak az első és az utolsó 4 karakter látható.

Kérés fejléc

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

Postman gyűjtemény

Ha neked kényelmesebb a Postman, mint a curl/SDK – van egy kész gyűjtemény az összes 771 végponttal, 55 mappára bontva az OpenAPI címkék szerint, beépített kérés példákkal. Az Auth a gyűjtemény szintjén van beállítva: egyszer beilleszted a kulcsot az apiKey változóba, és minden kérés felhasználja.

Közzétett dokumentáció: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Nyilvános munkaterület: postman.com/astroway-info/astroway-api
JSON letöltése: astroway-api.json (≈ 5 MB) - importáld közvetlenül a Postmanba vagy Insomnia

A gyűjtemény automatikusan generálva van a OpenAPI spec alapján – minden telepítéskor frissül.

Kulcsok létrehozása és kezelése

A dashboardon keresztül:

api.astroway.info/dashboard/keys
Legfeljebb 10 aktív kulcs lehet egy fiókban egyszerre
Minden kulcsnak van neve, a name mező (például production-backend, ci-tests, local-dev)

API-n keresztül (self-service integrációkhoz):

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

Böngésző kulcsok

A tipikus server-only kulcs: ha a kérés tartalmazza az Origin vagy Referer fejlécet, 403 ORIGIN_FORBIDDEN válasz érkezik. Ez szándékos, és ez az, ami elkapja a véletlenül a frontenden hagyott kulcsot.

Amikor egy widget vagy oldal a böngészőből kell, hogy az API-hoz forduljon, a kulcs azonnal az eredetpolitika szerint jön létre. Az origin_restriction mező a POST /v1/keys esetén:

`type`	Mi engedélyezett	Mikor használni
`server-only` (alapértelmezett)	csak `Origin` és `Referer` nélküli kérések	backend, cron, CI
`public`	csak a felsorolt hostok, és a kérés kötelezően tartalmazza az eredetet	widget vagy oldal a te domaineden, kulcs a forráskódban
`allowlist`	ugyanaz, mint a `public`	elavult írásmód: továbbra is elfogadott, de már nem szerepel az `openapi.json`-ban

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

Az egyezési szabályok, a prodon tesztelve:

Legfeljebb 20 host kulcsonként. A séma (https://) és a port figyelmen kívül marad, a kis- és nagybetű nem számít.
www. eltávolításra kerül a bemeneti hostból, így az example.com lefedi a www.example.com-t is. Nem kell külön www.-t hozzáadni, ez nem változtat semmit.
*.example.com lefedi az aldomain-eket (app.example.com), de nem a example.com-ot magát. A csillag sor külön sorban szerepel, ahogy a fenti példában.
A listán kívüli host 403 ORIGIN_NOT_ALLOWED választ kap, a incoming_origin mezőben a host névvel, hogy látható legyen, melyik sor hiányzik.
A Referer egyenlő súllyal számít a Origin-nal: a böngésző akkor küldi, ahol nincs Origin.

type: "public" egy pk_ osztályú kulcsot hoz létre, és számára a szabály fordított: egy Origin és Referer nélküli kérés 403 ORIGIN_REQUIRED választ kap, és nem úgy viselkedik, mint egy szerveres. Ezért a létrehozáskor három dolog kötelező: a domain lista, a credits_cap_cycle költségkeret és az allowed_endpoints terület (mindkettő le van írva alább). Ha valamelyik hiányzik, 400 válasz jön, és a pk_ kulcs, amelynek hiányzik a költségkeret vagy a terület, mindenhol 403 PUBLISHABLE_KEY_UNBOUNDED hibát ad. A kulcs a oldal kódjában bárki által olvasható, ezért soha nem lehet korlátlan. 2026-09-12-ig ez a mód azt jelentette, hogy “bármilyen origin”; 2026-09-24-től az ilyen kulcsok listát kaptak, amely a saját forgalmukból lett összegyűjtve, vagy szerveresek lettek, ha nem voltak böngésző kérések. A pk_ kulcs listájából származó origin szintén kap access-control-allow-origin fejlécet a /v1/* válaszokban, így az oldal olvashatja őket. A politikát a GET /v1/keys válaszban, az origin_restriction mezőben láthatod.

Meglévő kulcs listájának módosítása

PATCH /v1/keys/{id} felülírja a listát, a kulcsot érintetlenül hagyva. A hozzáférési jog ugyanaz, mint a POST /v1/keys esetén; a dashboardon ez a “Eredet módosítása” menüpont a kulcs menüben.

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

Az új lista a következő kérésnél lép életbe: a kulcs gyorsítótára íráskor törlődik, nem kell egy percet várni. Maga a kulcs sor nem változik, így sem az oldalt, sem a backendet újra kiadni nem kell. A POST /v1/keys/{id}/rotate után a lista megmarad, és a régi kulcs érték azonnal nem működik.

A kulcs osztálya nem szerkeszthető, mert az a kulcsban van tárolva:

Próbálkozás	Válasz
`pk_`-t `server-only`-ra változtatni	`400`: az osztály a kulcs része, vissza kell vonni és újat kell létrehozni
`aw_`-nak domain listát adni	`400`: a böngésző kulcs egy másik osztály, `public`-ként jön létre
`pk_` üres listával	`400`: egy listától mentes kulcs minden kérést elutasítana
`pk_` költségkeret vagy terület (`null`) nélkül	`400`: a böngésző kulcs mindig mindkettővel korlátozott, módosítható, de nem távolítható el

Kredit költségkeret egyedi kulcshoz

A kreditek közösek az egész fiókban, így egy kulcs el is fogyaszthatja őket. A backend kulcs esetén ez rendben van, de a oldal forráskódban lévő kulcsnál nem: a domain lista megmondja, honnan lehet hívni, de nem mondja meg, mennyibe kerül.

credits_cap_cycle ugyanabban a PATCH /v1/keys/{id}-ben korlátozza ezt a kulcsot:

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 eltávolítja a korlátozást (kivéve a pk_ kulcsot, amelynek a költségkeret módosítható, de nem távolítható el). 0 azt jelenti, hogy a kulcs semmit sem költhet: egy mód a kulcs parkoltatására, anélkül, hogy visszavonnád. A számláló ugyanaz, mint a krediteké, és a tarifaciklus végén nullázódik.

Amikor a kulcs eléri a költségkeretét, 429 KEY_BUDGET_EXHAUSTED válasz érkezik, még akkor is, ha a fiókban még vannak kreditek, és még overage tarifán is: a pénzért túlfogyasztható költségkeret nem költségkeret. Amíg a költségkeret be van állítva, minden válasz tartalmazza az X-Key-Budget-Limit és X-Key-Budget-Remaining fejléceket.

Végpontok területe

A terület nélküli kulcs mindent meghív, ami a tarifába tartozik. Az allowed_endpoints szűkíti a kulcsot egy útvonallistára: pontos (chart) vagy névtér (embed/*). Ez egy harmadik, független korlátozás: a domain lista megmondja, honnan, a költségkeret mennyit, a terület pedig mit.

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 eltávolítja a korlátozást (kivéve a pk_ kulcsot, amelynek a terület kötelező). Üres lista nem elfogadott: ugyanúgy értelmezhető lenne “mind” és “semmi”. Az útvonalak a /v1-hez relatívan írandók, kezdő perjel nélkül, a kis- és nagybetű nem számít.

A listán kívüli hívás 403 ENDPOINT_NOT_IN_SCOPE választ kap, a details mező a listát adja meg, hogy ne kelljen találgatni. A terület mindkét kulcsosztályra és a /v1/public/* és /v1/embed/* útvonalakra egyformán érvényes, mint a többi. A szolgáltatási olvasások nem mentesülnek tőle, a kreditektől eltérően: egy embed/*-ra szűkített kulcs nem olvassa a saját statisztikáját. Ez szándékos, mert egy oldal forráskódban lévő kulcsnak nem szabad a látogatónak a fiók költségeit visszaadnia, de a kulcs kezelése nem akadályozza: a dashboard sessionnel működik, nem kulccsal.

Legjobb gyakorlatok

1. Ne tedd a server-only kulcsot a frontendre

A tipikus kulcs a backend szint titka. Ha a felhasználó böngészőjében futó JS-be kerül, látható a DevTools-ban és kiszivárog. Ezért egy ilyen kulcs 403 ORIGIN_FORBIDDEN választ ad minden Origin vagy Referer tartalmazó kérésre.

Ha mégis a böngészőből kell hívni, ezt nem egy szokásos kulccsal, hanem egy külön, origin_restriction.type: "public"-vel létrehozott kulccsal teszed: böngésző kulcsok. Egy ilyen kulcs pk_ prefixummal rendelkezik, ez is látható a DevTools-ban, és ez a lényeg – az értéke a te domainjeid listájával korlátozott, és a origin nélküli kéréseket elutasítja.

Helyes: a saját backended tartja a kulcsot, a frontendre a backendedhez fordul, a te backended pedig az AstroWay API-hoz.

Helytelen:

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

2. Környezeti változók, ne hardcode-olj

# .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. Külön kulcsok külön környezetekhez

production-backend: production
staging-backend: staging
ci-tests: CI/CD pipeline
local-dev-maksym: minden fejlesztő helyi fejlesztése

Ha egy kulcs kompromittálódik – csak azt vonod vissza, a többi továbbra is működik.

4. Rotáció

Ajánlott gyakoriság – 90 naponta egyszer. Vagy azonnal, ha szivárgás gyanúja merül fel.

Rotáció leállás nélkül:

Hozz létre egy új kulcsot ugyanazzal a name-mel + -v2
Telepítsd a production környezetbe (párhuzamosan a régi kulccsal)
Győződj meg róla, hogy a használat az új kulcsra folyik (dashboard)
Vond vissza a régit

5. Használat monitorozása

A dashboard külön mutatja a kulcsok kéréseit. Ha hirtelen egy kulcs 10‑ször annyi kérést küld, mint általában – ez egy jelzés a ellenőrzésre.

Beállíthatsz riasztást: Settings → Notifications → Alert when daily credits > X.

Hitelesítési hibák

Kód	Leírás
`401 Unauthorized`	Header `X-Api-Key` hiányzik vagy a kulcs érvénytelen
`403 Forbidden`	A kulcs érvényes, de nincs megfelelő scope a művelethez (például egy normál kulcs megpróbál más kulcsokat kezelni)
`403 PUBLISHABLE_KEY_UNBOUNDED`	`pk_` kulcs költségkeret (`credits_cap_cycle`) vagy terület (`allowed_endpoints`) nélkül: állítsd be mindkettőt a kulcs beállításaiban
`402 Payment Required`	Kreditek elfogytak (Free esetén) vagy az előfizetés inaktív
`429 Too Many Requests`	Rate limit túllépve (10/60/300 kérés/perc a csomagtól függően)

Példa 401:

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

Sandbox mód

Az aw_test_ prefixummal rendelkező kulcsok sandboxban működnek:

Nem vonnak le krediteket
Stabil vagy minimális valós választ adnak
Nem befolyásolják a production statisztikát
Elérhető végpontok: ugyanazok

Hasznos CI/CD, e2e tesztekhez és helyi fejlesztéshez. Egy kattintással a dashboardon hozható létre.

Tovább

Kreditek és limitek: hogyan működik a számlázás és a rate limiting
Hibák: teljes lista a hibakódokról

Hasznos volt?

Javítás javaslata

Utoljára frissítve: 2026. okt. 4.