Authenticatie

Bijna alle verzoeken aan de AstroWay API authenticeren via de header X-Api-Key. Uitzonderingen: 14 endpoints /v1/reference/* (signs, planets, houses, aspects, …) werken openbaar zonder sleutel met een limiet van 30 verzoeken / uur per IP. Doet je server de verzoeken, stuur dan de header X-AstroWay-Site-URL mee en de limiet wordt 300 verzoeken / uur per site: details.

Krijg een API-sleutel in 60 seconden

aw_test_demo_aaaa1111

Aanmelden - gratis→

Voor alle rekenendpoints /v1/* (chart, synastry, transits, /reports, /tarot enzovoort) - alleen X-Api-Key. Voor gebruikersoperaties /v1/me/* (GET /me, DELETE /me/account) - een Bearer JWT, uitgegeven via /v1/auth/login. OAuth/session-cookies worden op de openbare API niet gebruikt. Reference-woordenboeken /v1/reference/* - zonder sleutel, gratis (canonieke lookup-tabellen).

Formaat van de sleutel

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

• aw_live_: productie, schrijft credits af van het saldo
• aw_test_: sandbox, verzoeken geven een stub-response terug (of een minimale echte berekening), schrijven geen credits af, apart gemarkeerd in het dashboard
• Na het prefix: 32 tekens base62, cryptografisch willekeurig
• De sleutel wordt maar één keer in leesbare vorm getoond, bij het aanmaken. Daarna toont het dashboard alleen de eerste en laatste 4 tekens.

Verzoekheader

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

Postman collection

Werk je liever met Postman dan met curl/SDK, dan is er een kant-en-klare collection met alle 771 endpoints, verdeeld over 55 mappen volgens de OpenAPI-tags, met ingevulde voorbeeldverzoeken. Auth is op collection-niveau ingesteld: je plakt de sleutel één keer in de variabele apiKey en alle verzoeken nemen hem over.

• Published docs: documenter.getpostman.com/view/54689779/2sBXqNmy3n
• Public workspace: postman.com/astroway-info/astroway-api
• JSON downloaden: astroway-api.json (≈ 5 MB) - importeer direct in Postman of Insomnia

De collection wordt automatisch gegenereerd uit de OpenAPI spec - bijgewerkt bij elke deploy.

Sleutels aanmaken en beheren

Via het dashboard:

• api.astroway.info/dashboard/keys
• Je kunt tot 10 actieve sleutels per account tegelijk hebben
• Elke sleutel heeft een naam, het veld name (bijvoorbeeld production-backend, ci-tests, local-dev)

Via de API (voor self-service-integraties):

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

Tip

De master-sleutel (die je in het dashboard hebt aangemaakt) kan andere sleutels beheren via /v1/keys. Gewone sleutels kunnen dat niet. Dat staat vastgelegd in de scope van de sleutel.

Sleutels voor de browser

Een standaardsleutel is server-only: draagt een verzoek ermee de header Origin of Referer, dan krijg je 403 ORIGIN_FORBIDDEN. Dat is bewust, en het vangt precies de sleutel die per ongeluk in een frontend is blijven staan.

Moet een widget of pagina vanuit de browser de API aanroepen, dan maak je de sleutel meteen aan met een originebeleid. Het veld origin_restriction in POST /v1/keys:

type	Wat is toegestaan	Wanneer gebruiken
server-only (standaard)	alleen verzoeken zonder Origin en Referer	backend, cron, CI
public	alleen de opgesomde hosts, en het verzoek moet een origine meesturen	een widget of pagina op je eigen domein, sleutel in de broncode
allowlist	hetzelfde als public	verouderde schrijfwijze: wordt nog geaccepteerd, maar staat niet meer 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/*"]
  }'

Matchingregels, gecontroleerd in productie:

• Tot 20 hosts per sleutel. Het schema (https://) en de poort worden genegeerd, hoofdletters maken niet uit.
• www. wordt van de inkomende host gehaald, dus example.com dekt ook www.example.com. De vorm met www. hoef je niet apart toe te voegen, dat verandert niets.
• *.example.com dekt subdomeinen (app.example.com), maar niet example.com zelf. De apex zet je als aparte regel in de lijst, zoals in het voorbeeld hierboven.
• Een host die niet in de lijst staat krijgt 403 ORIGIN_NOT_ALLOWED met de host zelf in het veld incoming_origin, zodat je ziet welke regel ontbreekt.
• Referer telt even zwaar als Origin: de browser stuurt die mee waar Origin ontbreekt.

Opgepast

type: "public" maakt een sleutel van de klasse pk_, en daarvoor geldt de omgekeerde regel: een verzoek zonder Origin en zonder Referer krijgt 403 ORIGIN_REQUIRED en gaat niet door als serververzoek. Daarom is de lijst al bij het aanmaken verplicht, anders krijg je 400. Tot 2026-09-12 betekende deze modus “elke origin”; op 2026-09-24 kregen de laatste van die sleutels een lijst die uit hun eigen verkeer was samengesteld, of werden ze serversleutels als ze geen browserverzoeken hadden. Een origin uit de lijst van een pk_-sleutel krijgt ook access-control-allow-origin in de responses van /v1/*, zodat de pagina ze kan lezen. Het beleid zie je in GET /v1/keys in het veld origin_restriction.

De lijst van een bestaande sleutel wijzigen

PATCH /v1/keys/{id} herschrijft de lijst zonder de sleutel zelf aan te raken. Het toegangsrecht is hetzelfde als bij POST /v1/keys hierboven; in het dashboard is dat het menu-item “Origine wijzigen” bij de sleutel.

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

De nieuwe lijst geldt vanaf het eerstvolgende verzoek: de cache van de sleutel wordt bij het wegschrijven geleegd, je hoeft geen minuut te wachten. De sleutelstring zelf verandert niet, dus je hoeft pagina noch backend opnieuw uit te rollen. Na POST /v1/keys/{id}/rotate blijft de lijst bewaard, en de oude waarde van de sleutel werkt direct niet meer.

De klasse van een sleutel is niet te wijzigen, omdat die in de sleutel zelf staat:

Poging	Response
pk_ omzetten naar server-only	400: de klasse is onderdeel van de sleutel, je moet hem intrekken en een nieuwe aanmaken
aw_ een domeinlijst geven	400: een browsersleutel is een andere klasse, die wordt aangemaakt als public
pk_ met een lege lijst	400: een sleutel zonder lijst zou elk verzoek weigeren

Creditbudget per sleutel

Credits zijn gedeeld over het hele account, dus één sleutel kan ze allemaal opmaken. Voor een backendsleutel is dat normaal, voor een sleutel in de broncode van een pagina niet: de domeinlijst zegt vanwaar je mag aanroepen, maar niet hoeveel het mag kosten.

credits_cap_cycle in dezelfde PATCH /v1/keys/{id} begrenst precies deze sleutel:

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 heft de begrenzing op. 0 betekent een sleutel waarmee je niets kunt uitgeven: een manier om een sleutel te parkeren zonder hem in te trekken. De teller is dezelfde als die van de credits en wordt samen met de cyclus van het plan op nul gezet.

Loopt een sleutel tegen zijn budget aan, dan krijg je 429 KEY_BUDGET_EXHAUSTED, ook als er op het account nog credits over zijn, en zelfs op een plan met overage: een budget dat je tegen betaling kunt overschrijden is geen budget. Zolang er een budget is ingesteld, bevat elke response X-Key-Budget-Limit en X-Key-Budget-Remaining.

Endpointbereik

Een sleutel zonder bereik roept alles aan wat in het plan zit. allowed_endpoints beperkt hem tot een lijst van paden: exact (chart) of een namespace (embed/*). Dit is de derde, onafhankelijke beperking: de domeinlijst zegt vanwaar, het budget hoeveel, het bereik wat precies.

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 heft de beperking op. Een lege lijst wordt niet geaccepteerd: die zou evengoed als “alles” als “niets” gelezen kunnen worden. Paden schrijf je relatief aan /v1, zonder slash vooraan, hoofdletters maken niet uit.

Een aanroep buiten de lijst krijgt 403 ENDPOINT_NOT_IN_SCOPE, en details noemt de lijst zelf, zodat je niet hoeft te raden. Het bereik geldt voor beide sleutelklassen en voor /v1/public/* en /v1/embed/* net zo als voor de rest. Service-reads zijn er, anders dan bij credits, niet van vrijgesteld: een sleutel die beperkt is tot embed/* kan ook zijn eigen statistieken niet lezen. Dat is bewust, want een sleutel in de broncode van een pagina mag de uitgaven van het account niet aan een bezoeker tonen, en het beheer van de sleutel hindert het niet: het dashboard werkt met een sessie, niet met de sleutel.

Best practices

1. Zet een server-only sleutel niet in de frontend

Een standaardsleutel is een geheim op backendniveau. Komt hij terecht in JS die in de browser van de gebruiker draait, dan is hij zichtbaar in DevTools en lekt hij uit. Juist daarom antwoordt zo’n sleutel met 403 ORIGIN_FORBIDDEN op elk verzoek met Origin of Referer.

Moet je toch vanuit de browser aanroepen, dan gebeurt dat niet met een gewone sleutel, maar met een aparte die is aangemaakt met origin_restriction.type: "public": sleutels voor de browser. Zo’n sleutel heeft het prefix pk_, is ook zichtbaar in DevTools, en dat is precies de bedoeling - zijn waarde is beperkt tot de lijst van je domeinen, en een verzoek zonder origine weigert hij.

Goed: je eigen backend houdt de sleutel, de frontend praat met jouw backend, jouw backend met de AstroWay API.

Fout:

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

2. Environment variables, geen 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. Aparte sleutels per omgeving

• production-backend: productie
• staging-backend: staging
• ci-tests: CI/CD-pipeline
• local-dev-maksym: lokale ontwikkeling per ontwikkelaar

Is één sleutel gecompromitteerd, dan trek je precies die in en blijven de andere werken.

4. Rotatie

Aanbevolen frequentie: eens per 90 dagen. Of meteen, als je een lek vermoedt.

Rotatie zonder downtime:

1. Maak een nieuwe sleutel aan met dezelfde name + -v2
2. Rol hem uit naar productie (naast de oude)
3. Controleer dat het gebruik naar de nieuwe sleutel gaat (dashboard)
4. Trek de oude in

5. Gebruik monitoren

Het dashboard toont verzoeken per sleutel apart. Begint één sleutel ineens 10× meer verzoeken te doen dan normaal, dan is dat een signaal om te controleren.

Je kunt een alert instellen: Settings → Notifications → Alert when daily credits > X.

Authenticatiefouten

Code	Betekenis
401 Unauthorized	De header X-Api-Key ontbreekt of de sleutel is ongeldig
403 Forbidden	De sleutel is geldig, maar heeft geen scope voor deze actie (bijvoorbeeld een gewone sleutel die andere sleutels probeert te beheren)
402 Payment Required	De credits zijn op (op Free) of het abonnement is niet actief
429 Too Many Requests	Rate limit overschreden (10/60/300 req/min afhankelijk van het plan)

Voorbeeld van 401:

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

Sandbox mode

Sleutels met het prefix aw_test_ werken in de sandbox:

• Schrijven geen credits af
• Geven een stub-response of een minimale echte response terug
• Hebben geen invloed op de productiestatistieken
• Beschikbare endpoints: dezelfde

Handig voor CI/CD, e2e-tests en lokale ontwikkeling. Aan te maken via het dashboard met één klik.

Verder

• Credits en limieten: hoe billing en rate limiting werken
• Fouten: de volledige lijst met error codes