Uwierzytelnianie

Niemal wszystkie żądania do AstroWay API są uwierzytelniane nagłówkiem X-Api-Key. Wyjątki: 14 endpointów /v1/reference/* (signs, planets, houses, aspects, …) działa publicznie bez klucza z limitem 30 żądań / godzinę na IP. Jeśli żądania wysyła Twój serwer, dodaj nagłówek X-AstroWay-Site-URL, a limit wzrośnie do 300 żądań / godzinę na stronę: szczegóły.

Zdobądź klucz API w 60 sekund

aw_test_demo_aaaa1111

Zarejestruj się - za darmo→

Dla wszystkich endpointów obliczeniowych /v1/* (chart, synastry, transits, /reports, /tarot itd.) - tylko X-Api-Key. Dla operacji użytkownika /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT wydany przez /v1/auth/login. OAuth i ciasteczka sesyjne nie są używane w publicznym API. Słowniki referencyjne /v1/reference/* - bez klucza, za darmo (kanoniczne tabele lookup).

Format klucza

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

• aw_live_: produkcja, pobiera kredyty z salda
• aw_test_: sandbox, żądania zwracają odpowiedź-zaślepkę (albo minimalne prawdziwe obliczenie), nie pobierają kredytów, są oznaczone w panelu osobno
• Po prefiksie: 32 znaki base62, kryptograficznie losowe
• Klucz jest pokazywany w czystej postaci tylko raz, przy tworzeniu. Później w panelu widać tylko pierwsze i ostatnie 4 znaki.

Nagłówek żądania

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

Kolekcja Postman

Jeśli wygodniejszy jest dla Ciebie Postman niż curl/SDK - jest gotowa kolekcja ze wszystkimi 771 endpointami, podzielona na 55 folderów według tagów OpenAPI, z podstawionymi przykładami żądań. Auth jest skonfigurowany na poziomie kolekcji: wklejasz klucz do zmiennej apiKey raz, a wszystkie żądania go podchwytują.

• Opublikowana dokumentacja: documenter.getpostman.com/view/54689779/2sBXqNmy3n
• Publiczny workspace: postman.com/astroway-info/astroway-api
• Pobierz JSON: astroway-api.json (≈ 5 MB) - zaimportuj bezpośrednio do Postman lub Insomnia

Kolekcja jest generowana automatycznie ze specyfikacji OpenAPI - aktualizuje się przy każdym deployu.

Tworzenie kluczy i zarządzanie nimi

Przez panel:

• api.astroway.info/dashboard/keys
• Możesz mieć jednocześnie do 10 aktywnych kluczy na konto
• Każdy klucz ma nazwę, pole name (na przykład production-backend, ci-tests, local-dev)

Przez API (dla integracji 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

Wskazówka

Klucz master (ten, który utworzyłeś w panelu) może zarządzać innymi kluczami przez /v1/keys. Zwykłe klucze - nie mogą. Jest to zapisane w scope klucza.

Klucze dla przeglądarki

Domyślny klucz jest server-only: jeśli żądanie z nim niesie nagłówek Origin lub Referer, przychodzi 403 ORIGIN_FORBIDDEN. To celowe i właśnie to wyłapuje klucz przypadkowo zostawiony we frontendzie.

Gdy widżet lub strona mają odpytywać API z przeglądarki, klucz tworzy się od razu z polityką pochodzenia. Pole origin_restriction w POST /v1/keys:

type	Co jest dozwolone	Kiedy wybrać
server-only (domyślnie)	tylko żądania bez Origin i Referer	backend, cron, CI
public	tylko wymienione hosty, a żądanie musi nieść pochodzenie	widżet lub strona w Twojej domenie, klucz w kodzie źródłowym
allowlist	to samo co public	przestarzała pisownia: nadal akceptowana, ale w openapi.json już nie figuruje

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

Reguły dopasowania, sprawdzone na produkcji:

• Do 20 hostów na klucz. Schemat (https://) i port są ignorowane, wielkość liter nie ma znaczenia.
• www. jest zdejmowane z hosta przychodzącego, więc example.com obejmuje też www.example.com. Nie trzeba osobno dodawać formy z www., niczego to nie zmienia.
• *.example.com obejmuje subdomeny (app.example.com), ale nie samą example.com. Domenę główną wymienia się w osobnym wierszu, jak w przykładzie wyżej.
• Host spoza listy dostaje 403 ORIGIN_NOT_ALLOWED z samym hostem w polu incoming_origin, żeby było widać, którego wiersza brakuje.
• Referer liczy się na równi z Origin: przeglądarka wysyła go tam, gdzie Origin nie ma.

Uwaga

type: "public" tworzy klucz klasy pk_ i dla niego reguła jest odwrotna: żądanie bez Origin i bez Referer dostaje 403 ORIGIN_REQUIRED, zamiast przejść jako serwerowe. Dlatego lista jest obowiązkowa już przy tworzeniu, inaczej przychodzi 400. Do 2026-09-12 ten tryb oznaczał “dowolny origin”; 2026-09-24 ostatnie takie klucze dostały listę zebraną z ich własnego ruchu albo stały się serwerowymi, jeśli nie miały żądań z przeglądarki. Origin z listy klucza pk_ dostaje też access-control-allow-origin w odpowiedziach /v1/*, więc strona może je odczytać. Politykę widać w GET /v1/keys w polu origin_restriction.

Zmiana listy w już utworzonym kluczu

PATCH /v1/keys/{id} nadpisuje listę, nie ruszając samego klucza. Uprawnienia są te same co w POST /v1/keys wyżej; w panelu to pozycja “Zmień pochodzenie” w menu klucza.

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

Nowa lista działa od następnego żądania: cache klucza jest czyszczony przy zapisie, nie trzeba czekać minuty. Sam ciąg klucza się nie zmienia, więc ani strony, ani backendu nie trzeba wydawać ponownie. Po POST /v1/keys/{id}/rotate lista zostaje zachowana, a stara wartość klucza przestaje działać natychmiast.

Klasy klucza nie da się edytować, bo jest zapisana w samym kluczu:

Próba	Odpowiedź
pk_ zmienić na server-only	400: klasa jest częścią klucza, trzeba go unieważnić i utworzyć nowy
aw_ dać listę domen	400: klucz przeglądarkowy to inna klasa, tworzy się go jako public
pk_ z pustą listą	400: klucz bez listy odrzucałby każde żądanie

Budżet kredytów dla pojedynczego klucza

Kredyty są wspólne dla całego konta, więc jeden klucz może wydać je wszystkie. Dla klucza backendowego to normalne, dla klucza w kodzie źródłowym strony już nie: lista domen mówi, skąd można się odwoływać, ale nie mówi, ile to może kosztować.

credits_cap_cycle w tym samym PATCH /v1/keys/{id} ogranicza właśnie ten klucz:

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 zdejmuje ograniczenie. 0 oznacza klucz, którym nie można wydać niczego: sposób, by zaparkować klucz bez unieważniania go. Licznik jest ten sam co dla kredytów i zeruje się razem z cyklem planu.

Gdy klucz dochodzi do swojego budżetu, przychodzi 429 KEY_BUDGET_EXHAUSTED, nawet jeśli na koncie zostały jeszcze kredyty, i nawet na planie z overage: budżet, który można przekroczyć za pieniądze, nie jest budżetem. Dopóki budżet jest ustawiony, każda odpowiedź niesie X-Key-Budget-Limit i X-Key-Budget-Remaining.

Zakres endpointów

Klucz bez zakresu wywołuje wszystko, co obejmuje plan. allowed_endpoints zawęża go do listy ścieżek: dokładnej (chart) albo przestrzeni nazw (embed/*). To trzecie, niezależne ograniczenie: lista domen mówi skąd, budżet ile, zakres co dokładnie.

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 zdejmuje ograniczenie. Pusta lista nie jest akceptowana: czytałaby się jednakowo jako “wszystko” i jako “nic”. Ścieżki pisze się względem /v1, bez początkowego ukośnika, wielkość liter nie ma znaczenia.

Wywołanie spoza listy dostaje 403 ENDPOINT_NOT_IN_SCOPE, a details podaje samą listę, żeby nie trzeba było zgadywać. Zakres działa na obie klasy kluczy oraz na /v1/public/* i /v1/embed/* tak samo jak na resztę. Odczyty serwisowe nie są z niego zwolnione, w przeciwieństwie do kredytów: klucz zawężony do embed/* nie odczyta nawet własnych statystyk. To celowe, bo klucz w kodzie źródłowym strony nie powinien zdradzać odwiedzającemu wydatków konta, a zarządzaniu kluczem to nie przeszkadza: panel działa na sesji, a nie na kluczu.

Dobre praktyki

1. Nie umieszczaj klucza server-only we frontendzie

Domyślny klucz to sekret poziomu backendu. Jeśli trafi do JS wykonywanego w przeglądarce użytkownika - widać go w DevTools i wycieknie. Właśnie dlatego taki klucz odpowiada 403 ORIGIN_FORBIDDEN na każde żądanie z Origin lub Referer.

Jeśli odwoływać się z przeglądarki jednak trzeba, robi się to nie zwykłym kluczem, a osobnym, utworzonym z origin_restriction.type: "public": klucze dla przeglądarki. Taki klucz ma prefiks pk_, też widać go w DevTools i o to właśnie chodzi - jego wartość jest ograniczona listą Twoich domen, a żądanie bez pochodzenia odrzuca.

Poprawnie: Twój backend trzyma klucz, frontend odpytuje Twój backend, Twój backend - AstroWay API.

Niepoprawnie:

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

2. Zmienne środowiskowe, nie 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. Osobne klucze dla różnych środowisk

• production-backend: produkcja
• staging-backend: staging
• ci-tests: pipeline CI/CD
• local-dev-maksym: lokalny development każdego programisty

Jeśli jeden klucz zostanie skompromitowany - unieważniasz właśnie jego, a pozostałe działają dalej.

4. Rotacja

Zalecana częstotliwość - raz na 90 dni. Albo natychmiast, jeśli istnieje podejrzenie wycieku.

Rotacja bez przestoju:

1. Utwórz nowy klucz o tej samej name + -v2
2. Wdróż go na produkcję (równolegle ze starym)
3. Upewnij się, że ruch płynie na nowy klucz (panel)
4. Unieważnij stary

5. Monitorowanie użycia

Panel pokazuje żądania osobno dla każdego klucza. Jeśli nagle jeden klucz zaczął wysyłać 10× więcej żądań niż zwykle - to sygnał, żeby to sprawdzić.

Można ustawić alert: Settings → Notifications → Alert when daily credits > X.

Błędy uwierzytelniania

Kod	Znaczenie
401 Unauthorized	Brak nagłówka X-Api-Key albo klucz jest nieprawidłowy
403 Forbidden	Klucz jest prawidłowy, ale nie ma scope dla tej akcji (np. zwykły klucz próbuje zarządzać innymi kluczami)
402 Payment Required	Kredyty się skończyły (na Free) albo subskrypcja jest nieaktywna
429 Too Many Requests	Przekroczono rate limit (10/60/300 req/min zależnie od planu)

Przykład 401:

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

Tryb sandbox

Klucze z prefiksem aw_test_ działają w sandboxie:

• Nie pobierają kredytów
• Zwracają odpowiedź-zaślepkę albo minimalną prawdziwą odpowiedź
• Nie wpływają na statystyki produkcyjne
• Dostępne endpointy: te same

Przydatne dla CI/CD, testów e2e i lokalnego developmentu. Tworzy się go w panelu jednym kliknięciem.

Dalej

• Kredyty i limity: jak działa rozliczanie i rate limiting
• Błędy: pełna lista kodów błędów