Autentizace

Téměř všechny požadavky na AstroWay API se autentizují pomocí hlavičky X-Api-Key. Výjimky: 14 endpointů /v1/reference/* (signs, planets, houses, aspects, …) funguje veřejně bez klíče s omezením 30 požadavků / hodinu na IP. Pokud požadavky provádí tvůj server, odešli hlavičku X-AstroWay-Site-URL a limit se stane 300 požadavků / hodinu na web: detaily.

Pro všechny výpočetní endpointy /v1/* (chart, synastry, transits, /reports, /tarot atd.) - pouze X-Api-Key. Pro uživatelské operace /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, vydaný přes /v1/auth/login. OAuth/session-cookies se na veřejném API nepoužívají. Referenční slovníky /v1/reference/* - bez klíče, zdarma (kanonické lookup-tabulky).

Formát klíče

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: produkce, strhává kredity z zůstatku
aw_test_: sandbox, požadavky vracejí stubovou odpověď (nebo minimální reálný výpočet), nestrhávají kredity, jsou označeny v dashboardu zvlášť
Po prefixu: 32 znaků base62, kryptograficky náhodné
Klíč se zobrazí v čisté podobě pouze jednou při vytvoření. Dále v dashboardu - pouze první a poslední 4 znaky.

Hlavička požadavku

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

Postman kolekce

Pokud je pro tebe Postman pohodlnější než curl/SDK - je k dispozici hotová kolekce se všemi 771 endpointy, rozdělená do 55 složek podle OpenAPI tagů, s přednastavenými příklady požadavků. Auth je nastaven na úrovni kolekce: vložíš klíč do apiKey variable jednou, všechny požadavky ho převezmou.

Publikovaná dokumentace: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Veřejný workspace: postman.com/astroway-info/astroway-api
Stáhnout JSON: astroway-api.json (≈ 5 MB) - importuj přímo do Postmanu nebo Insomnie

Kolekce je automaticky generována z OpenAPI spec - aktualizuje se s každým nasazením.

Vytváření a správa klíčů

Přes dashboard:

api.astroway.info/dashboard/keys
Můžeš mít až 10 aktivních klíčů na účet současně
Každý klíč má jméno, pole name (například production-backend, ci-tests, local-dev)

Přes API (pro self-service integrace):

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

Klíče pro prohlížeč

Typický klíč server-only: pokud požadavek s ním nese hlavičku Origin nebo Referer, přijde 403 ORIGIN_FORBIDDEN. To je záměrné, a to je to, co zachytí klíč, náhodně ponechaný ve frontendovém kódu.

Když widget nebo stránka mají přistupovat k API z prohlížeče, klíč se vytvoří rovnou s politikou původu. Pole origin_restriction v POST /v1/keys:

`type`	Co je povoleno	Kdy použít
`server-only` (výchozí)	pouze požadavky bez `Origin` a `Referer`	backend, cron, CI
`public`	pouze uvedené hosty, a požadavek musí nést původ	widget nebo stránka na tvé doméně, klíč ve zdrojovém kódu
`allowlist`	to samé jako `public`	zastaralé označení: je stále přijímáno, ale v `openapi.json` se již neuvádí

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

Pravidla porovnávání, ověřená v produkci:

Až 20 hostů na klíč. Schéma (https://) a port jsou ignorovány, na velikosti písmen nezáleží.
www. se odstraní z příchozího hosta, takže example.com pokrývá i www.example.com. Není třeba přidávat formu s www. zvlášť, nic to nemění.
*.example.com pokrývá subdomény (app.example.com), ale ne samotný example.com. Apex se uvádí na samostatném řádku, jako v příkladu výše.
Host, který není v seznamu, obdrží 403 ORIGIN_NOT_ALLOWED se samotným hostem v poli incoming_origin, aby bylo vidět, který řádek chybí.
Referer se počítá stejně jako Origin: prohlížeč ho odesílá tam, kde Origin chybí.

type: "public" vytvoří klíč třídy pk_, a pro něj platí opačné pravidlo: požadavek bez Origin a bez Referer obdrží 403 ORIGIN_REQUIRED, a neprojde jako serverový. Proto jsou při vytvoření povinné tři věci: seznam domén, rozpočet credits_cap_cycle a rozsah allowed_endpoints (oba popsány níže). Bez kteréhokoli z nich přijde 400, a klíč pk_, kterému chybí rozpočet nebo rozsah, je všude odmítnut s 403 PUBLISHABLE_KEY_UNBOUNDED. Klíč v kódu stránky může přečíst každý, takže nikdy není neomezený. Do 2026-09-12 tento režim znamenal “jakýkoli origin”; 2026-09-24 poslední takové klíče obdržely seznam, shromážděný z jejich vlastního provozu, nebo se staly serverovými, pokud neměly prohlížečové požadavky. Origin ze seznamu klíče pk_ také obdrží access-control-allow-origin v odpovědích /v1/*, takže stránka je může přečíst. Politika je viditelná v GET /v1/keys v poli origin_restriction.

Změnit seznam u již vytvořeného klíče

PATCH /v1/keys/{id} přepíše seznam, aniž by se dotkl samotného klíče. Přístupové právo je stejné jako u POST /v1/keys výše; v dashboardu je to položka “Změnit původ” v menu klíče.

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

Nový seznam platí od následujícího požadavku: cache klíče se resetuje během zápisu, není třeba čekat minutu. Samotný řetězec klíče se nemění, takže není třeba znovu vydávat ani stránku, ani backend. Po POST /v1/keys/{id}/rotate se seznam uloží a stará hodnota klíče přestane fungovat okamžitě.

Třída klíče se neupravuje, protože je zapsána v samotném klíči:

Pokus	Odpověď
`pk_` udělat `server-only`	`400`: třída je součástí klíče, je třeba ji zrušit a vytvořit nový
`aw_` dát seznam domén	`400`: prohlížečový klíč je jiná třída, vytváří se jako `public`
`pk_` s prázdným seznamem	`400`: klíč bez seznamu by odmítl každý požadavek
`pk_` bez rozpočtu nebo rozsahu (`null`)	`400`: klíč pro prohlížeč je vždy omezen oběma, lze je změnit, ale ne odstranit

Rozpočet kreditů na samostatný klíč

Kredity jsou sdílené pro celý účet, takže jeden klíč je může všechny utratit. Pro backendový klíč je to normální, pro klíč ve zdrojovém kódu stránky ne: seznam domén říká, odkud lze přistupovat, ale neříká, kolik to může stát.

credits_cap_cycle ve stejném PATCH /v1/keys/{id} omezuje právě tento klíč:

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 odstraní omezení (kromě klíče pk_, u něj lze rozpočet změnit, ale ne odstranit). 0 znamená klíč, kterým nelze utratit nic: způsob, jak zaparkovat klíč, aniž bys ho zrušil. Počítadlo je stejné jako u kreditů a vynuluje se spolu s cyklem tarifu.

Když klíč narazí na svůj rozpočet, přijde 429 KEY_BUDGET_EXHAUSTED, i když na účtu kredity ještě zbyly, a dokonce i na tarifu s overage: rozpočet, který lze přečerpat za peníze, není rozpočet. Dokud je rozpočet nastaven, každá odpověď nese X-Key-Budget-Limit a X-Key-Budget-Remaining.

Rozsah endpointů

Klíč bez rozsahu volá vše, co je zahrnuto v tarifu. allowed_endpoints ho zužuje na seznam cest: přesných (chart) nebo jmenného prostoru (embed/*). Toto je třetí, nezávislé omezení: seznam domén říká odkud, rozpočet kolik, rozsah co přesně.

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 odstraní omezení (kromě klíče pk_, u něj je rozsah povinný). Prázdný seznam není přijímán: četl by se stejně jako “všechno” i jako “nic”. Cesty se píší relativně k /v1, bez počátečního lomítka, na velikosti písmen nezáleží.

Volání mimo seznam obdrží 403 ENDPOINT_NOT_IN_SCOPE, a details pojmenuje samotný seznam, aby nebylo třeba hádat. Rozsah platí pro obě třídy klíčů a pro /v1/public/* a /v1/embed/* stejně jako pro zbytek. Služební čtení zpod ní nejsou osvobozena, na rozdíl od kreditů: klíč, zúžený na embed/*, nepřečte ani vlastní statistiku. To je záměrné, protože klíč ve zdrojovém kódu stránky by neměl návštěvníkovi vydávat náklady účtu, a správě klíče to nebrání: dashboard přistupuje se session, nikoli s klíčem.

Osvědčené postupy

1. Neumisťuj server-only klíč do frontendu

Typický klíč je tajemství na úrovni backendu. Pokud se dostane do JS, který se spouští v prohlížeči uživatele - je viditelný v DevTools a unikne. Právě proto takový klíč odpovídá 403 ORIGIN_FORBIDDEN na jakýkoli požadavek s Origin nebo Referer.

Pokud je přistupování z prohlížeče přesto nutné, nedělá se to běžným klíčem, ale samostatným, vytvořeným s origin_restriction.type: "public": klíče pro prohlížeč. Takový klíč má prefix pk_, je také viditelný v DevTools, a v tom je celá podstata - jeho hodnota je omezena seznamem tvých domén, a požadavek bez původu odmítá.

Správně: tvůj backend drží klíč, frontend volá tvůj backend, tvůj backend - AstroWay API.

Nesprávně:

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

2. Proměnné prostředí, ne 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. Samostatné klíče pro různá prostředí

production-backend: produkce
staging-backend: staging
ci-tests: CI/CD pipeline
local-dev-maksym: lokální vývoj každého vývojáře

Pokud je jeden klíč kompromitován - zruš právě ten, ostatní pokračují v práci.

4. Rotace

Doporučená frekvence - jednou za 90 dní. Nebo okamžitě, pokud existuje podezření na únik.

Rotace bez downtime:

Vytvoř nový klíč se stejným name + -v2
Nasaď ho do produkce (paralelně se starým)
Ujisti se, že usage proudí na nový klíč (dashboard)
Zruš starý

5. Monitorování usage

Dashboard zobrazuje požadavky podle klíčů samostatně. Pokud najednou jeden klíč začal provádět 10× více požadavků než obvykle - je to signál k prověření.

Můžeš nastavit alert: Settings → Notifications → Alert when daily credits > X.

Chyby autentizace

Kód	Význam
`401 Unauthorized`	Hlavička `X-Api-Key` chybí nebo klíč není platný
`403 Forbidden`	Klíč je platný, ale nemá scope pro tuto akci (například běžný klíč se pokouší spravovat jiné klíče)
`403 PUBLISHABLE_KEY_UNBOUNDED`	Klíč `pk_` bez rozpočtu `credits_cap_cycle` nebo bez rozsahu `allowed_endpoints`: nastav obojí v nastavení klíče
`402 Payment Required`	Kredity došly (na Free) nebo předplatné není aktivní
`429 Too Many Requests`	Překročen rate limit (10/60/300 req/min v závislosti na plánu)

Příklad 401:

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

Sandbox režim

Klíče s prefixem aw_test_ fungují v sandboxu:

Nestrhávají kredity
Vracejí stubovou nebo minimální reálnou odpověď
Neovlivňují produkční statistiky
Dostupné endpointy: ty samé

Užitečné pro CI/CD, e2e testy a lokální vývoj. Vytváří se přes dashboard jedním kliknutím.

Dále

Kredity a limity: jak funguje billing a rate limiting
Chyby: úplný seznam error-kódů

Užitečné?

Navrhnout úpravu

Aktualizováno: 4. 10. 2026