Authentifizierung

Fast alle Anfragen an die AstroWay API werden über den Header X-Api-Key authentifiziert. Ausnahmen: 14 Endpunkte /v1/reference/* (signs, planets, houses, aspects, …) funktionieren öffentlich ohne Schlüssel mit einer Begrenzung von 30 Anfragen / Stunde pro IP. Wenn dein Server die Anfragen stellt, sende den Header X-AstroWay-Site-URL und das Limit wird auf 300 Anfragen / Stunde pro Website erhöht: Details.

Hole dir deinen API-Schlüssel in 60 Sekunden

aw_test_demo_aaaa1111

Kostenlos registrieren→

Für alle berechnenden Endpunkte /v1/* (chart, synastry, transits, /reports, /tarot usw.) - nur X-Api-Key. Für Benutzeroperationen /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, ausgestellt über /v1/auth/login. OAuth/Session-Cookies werden auf der öffentlichen API nicht verwendet. Referenz-Wörterbücher /v1/reference/* - ohne Schlüssel, kostenlos (kanonische Lookup-Tabellen).

Schlüsselformat

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

• aw_live_: Produktion, bucht Credits vom Guthaben ab
• aw_test_: Sandbox, Anfragen geben eine Stub-Antwort (oder eine minimale reale Berechnung) zurück, buchen keine Credits ab, werden im Dashboard separat gekennzeichnet
• Nach dem Präfix: 32 base62-Zeichen, kryptografisch zufällig
• Der Schlüssel wird nur einmal bei der Erstellung im Klartext angezeigt. Danach im Dashboard - nur die ersten und letzten 4 Zeichen.

Anfrage-Header

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

Postman Collection

Wenn Postman für dich bequemer ist als curl/SDK - es gibt eine fertige Collection mit allen 771 Endpunkten, aufgeteilt in 55 Ordner nach OpenAPI-Tags, mit eingefügten Beispielanfragen. Die Authentifizierung ist auf Collection-Ebene eingerichtet: Du fügst den Schlüssel einmal in die apiKey-Variable ein, und alle Anfragen übernehmen ihn.

• Veröffentlichte Dokumente: documenter.getpostman.com/view/54689779/2sBXqNmy3n
• Öffentlicher Workspace: postman.com/astroway-info/astroway-api
• JSON herunterladen: astroway-api.json (≈ 5 MB) - direkt in Postman oder Insomnia importieren

Die Collection wird automatisch aus der OpenAPI-Spezifikation generiert - sie wird mit jedem Deployment aktualisiert.

Schlüssel erstellen und verwalten

Über das Dashboard:

• api.astroway.info/dashboard/keys
• Du kannst bis zu 10 aktive Schlüssel gleichzeitig pro Konto haben
• Jeder Schlüssel hat einen Namen, das Feld name (z.B. production-backend, ci-tests, local-dev)

Über die API (für Self-Service-Integrationen):

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

Tipp

Der Master-Schlüssel (den du im Dashboard erstellt hast) kann andere Schlüssel über /v1/keys verwalten. Reguläre Schlüssel können das nicht. Dies ist im scope des Schlüssels festgelegt.

Schlüssel für den Browser

Ein typischer server-only-Schlüssel: Wenn eine Anfrage mit ihm den Header Origin oder Referer enthält, wird 403 ORIGIN_FORBIDDEN zurückgegeben. Dies ist beabsichtigt und fängt Schlüssel ab, die versehentlich im Frontend hinterlassen wurden.

Wenn ein Widget oder eine Seite die API vom Browser aus aufrufen soll, wird der Schlüssel sofort mit einer Ursprungsrichtlinie erstellt. Das Feld origin_restriction in POST /v1/keys:

type	Was erlaubt ist	Wann zu verwenden
server-only (Standard)	nur Anfragen ohne Origin und Referer	Backend, Cron, CI
public	nur gelistete Hosts, und die Anfrage muss einen Origin enthalten	Widget oder Seite auf deiner Domain, Schlüssel im Quellcode
allowlist	dasselbe wie public	veraltete Schreibweise: wird weiterhin akzeptiert, ist aber nicht mehr in openapi.json aufgeführt

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

Abgleichregeln, in Produktion getestet:

• Bis zu 20 Hosts pro Schlüssel. Schema (https://) und Port werden ignoriert, Groß-/Kleinschreibung spielt keine Rolle.
• www. wird vom eingehenden Host entfernt, sodass example.com auch www.example.com abdeckt. Es ist nicht nötig, die Form mit www. separat hinzuzufügen, sie ändert nichts.
• *.example.com deckt Subdomains (app.example.com) ab, aber nicht example.com selbst. Der Apex wird als separate Zeile aufgeführt, wie im obigen Beispiel.
• Ein Host, der nicht in der Liste ist, erhält 403 ORIGIN_NOT_ALLOWED mit dem Host selbst im Feld incoming_origin, um zu zeigen, welche Zeile fehlt.
• Referer wird gleichwertig mit Origin behandelt: Der Browser sendet ihn, wenn Origin nicht vorhanden ist.

Achtung

type: "public" erstellt einen Schlüssel der Klasse pk_, und für diesen ist die Regel umgekehrt: Eine Anfrage ohne Origin und ohne Referer erhält 403 ORIGIN_REQUIRED und wird nicht als Serveranfrage durchgelassen. Daher sind bei der Erstellung drei Dinge obligatorisch: die Liste der Domains, das Budget credits_cap_cycle und der Bereich allowed_endpoints (beide unten beschrieben). Ohne eines davon wird 400 zurückgegeben, und ein pk_-Schlüssel, dem Budget oder Bereich fehlen, wird überall mit 403 PUBLISHABLE_KEY_UNBOUNDED abgelehnt. Ein Schlüssel im Seitenquellcode kann von jedem gelesen werden, daher ist er niemals unbegrenzt. Bis zum 12.09.2026 bedeutete dieser Modus “jeder Origin”; am 24.09.2026 erhielten die letzten solcher Schlüssel eine Liste, die aus ihrem eigenen Traffic gesammelt wurde, oder wurden zu Server-Schlüsseln, wenn sie keine Browser-Anfragen hatten. Der Origin aus der pk_-Schlüsselliste erhält auch access-control-allow-origin in den /v1/*-Antworten, sodass die Seite sie lesen kann. Die Richtlinie ist in GET /v1/keys im Feld origin_restriction sichtbar.

Liste eines bereits erstellten Schlüssels ändern

PATCH /v1/keys/{id} überschreibt die Liste, ohne den Schlüssel selbst zu ändern. Die Zugriffsrechte sind dieselben wie bei POST /v1/keys oben; im Dashboard ist dies der Punkt “Herkunft ändern” im Schlüsselmenü.

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

Die neue Liste ist ab der nächsten Anfrage gültig: Der Schlüssel-Cache wird beim Schreiben zurückgesetzt, du musst keine Minute warten. Die Schlüsselzeichenfolge selbst ändert sich nicht, sodass weder die Seite noch das Backend neu veröffentlicht werden müssen. Nach POST /v1/keys/{id}/rotate bleibt die Liste erhalten, und der alte Schlüsselwert funktioniert sofort nicht mehr.

Die Schlüsselklasse kann nicht bearbeitet werden, da sie im Schlüssel selbst gespeichert ist:

Versuch	Antwort
pk_ zu server-only machen	400: Die Klasse ist Teil des Schlüssels, du musst ihn widerrufen und einen neuen erstellen
aw_ eine Liste von Domains geben	400: Ein Browser-Schlüssel ist eine andere Klasse, er wird als public erstellt
pk_ mit leerer Liste	400: Ein Schlüssel ohne Liste würde jede Anfrage ablehnen
pk_ ohne Budget oder Bereich (null)	400: Ein Schlüssel für den Browser ist immer durch beides begrenzt, sie können geändert, aber nicht entfernt werden

Credit-Budget pro Schlüssel

Credits sind kontoübergreifend, sodass ein Schlüssel alle verbrauchen kann. Für einen Backend-Schlüssel ist das normal, für einen Schlüssel im Quellcode einer Seite jedoch nicht: Die Domainliste sagt, woher Anfragen kommen dürfen, aber nicht, wie viel das kosten darf.

credits_cap_cycle im selben PATCH /v1/keys/{id} begrenzt genau diesen Schlüssel:

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 hebt die Beschränkung auf (außer für pk_-Schlüssel, bei denen das Budget geändert, aber nicht entfernt werden kann). 0 bedeutet einen Schlüssel, mit dem nichts ausgegeben werden kann: eine Möglichkeit, einen Schlüssel zu parken, ohne ihn zu widerrufen. Der Zähler ist derselbe wie für Credits und wird zusammen mit dem Tarifzyklus zurückgesetzt.

Wenn ein Schlüssel sein Budget erreicht, wird 429 KEY_BUDGET_EXHAUSTED zurückgegeben, selbst wenn noch Credits auf dem Konto vorhanden sind und selbst bei einem Tarif mit Overage: Ein Budget, das gegen Bezahlung überschritten werden kann, ist kein Budget. Solange ein Budget festgelegt ist, enthält jede Antwort X-Key-Budget-Limit und X-Key-Budget-Remaining.

Endpunktbereich

Ein Schlüssel ohne Bereich ruft alles auf, was im Tarif enthalten ist. allowed_endpoints schränkt ihn auf eine Liste von Pfaden ein: exakt (chart) oder einen Namensraum (embed/*). Dies ist die dritte, unabhängige Beschränkung: Die Domainliste sagt, woher, das Budget wie viel, der Bereich was genau.

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 hebt die Beschränkung auf (außer für pk_-Schlüssel, bei denen der Bereich obligatorisch ist). Eine leere Liste wird nicht akzeptiert: Sie würde gleichermaßen als “alles” und als “nichts” gelesen werden. Pfade werden relativ zu /v1 geschrieben, ohne führenden Schrägstrich, Groß-/Kleinschreibung spielt keine Rolle.

Ein Aufruf außerhalb der Liste erhält 403 ENDPOINT_NOT_IN_SCOPE, und details nennt die Liste selbst, damit du nicht raten musst. Der Bereich gilt für beide Schlüsselklassen und für /v1/public/* sowie /v1/embed/* genauso wie für den Rest. Dienstliche Lesevorgänge sind davon nicht ausgenommen, im Gegensatz zu Credits: Ein Schlüssel, der auf embed/* beschränkt ist, kann seine eigene Statistik nicht lesen. Dies ist beabsichtigt, da ein Schlüssel im Quellcode einer Seite dem Besucher nicht die Kontokosten preisgeben sollte, und es die Schlüsselverwaltung nicht behindert: Das Dashboard verwendet eine Sitzung, keinen Schlüssel.

Best Practices

1. Lege server-only Schlüssel nicht ins Frontend

Ein typischer Schlüssel ist ein Backend-Geheimnis. Wenn er in JavaScript gelangt, das im Browser des Benutzers ausgeführt wird, ist er in den DevTools sichtbar und wird geleakt. Deshalb antwortet ein solcher Schlüssel mit 403 ORIGIN_FORBIDDEN auf jede Anfrage mit Origin oder Referer.

Wenn du dennoch vom Browser aus zugreifen musst, geschieht dies nicht mit einem normalen Schlüssel, sondern mit einem separaten, der mit origin_restriction.type: "public" erstellt wurde: Schlüssel für den Browser. Ein solcher Schlüssel hat das Präfix pk_, ist ebenfalls in den DevTools sichtbar, und das ist der ganze Punkt - sein Wert ist auf die Liste deiner Domains beschränkt, und eine Anfrage ohne Origin lehnt er ab.

Richtig: Dein Backend hält den Schlüssel, das Frontend ruft dein Backend auf, dein Backend ruft die AstroWay API auf.

Falsch:

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

2. Umgebungsvariablen, kein Hardcoding

# .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. Separate Schlüssel für verschiedene Umgebungen

• production-backend: Produktion
• staging-backend: Staging
• ci-tests: CI/CD-Pipeline
• local-dev-maksym: lokale Entwicklung jedes Entwicklers

Wenn ein Schlüssel kompromittiert ist - widerrufe genau diesen, die anderen funktionieren weiter.

4. Rotation

Empfohlene Häufigkeit - alle 90 Tage. Oder sofort, wenn ein Leak vermutet wird.

Rotation ohne Downtime:

1. Erstelle einen neuen Schlüssel mit demselben name + -v2
2. Rolle ihn in der Produktion aus (parallel zum alten)
3. Stelle sicher, dass die Nutzung auf den neuen Schlüssel übergeht (Dashboard)
4. Widerrufe den alten

5. Nutzungsüberwachung

Das Dashboard zeigt Anfragen pro Schlüssel separat an. Wenn ein Schlüssel plötzlich 10x mehr Anfragen als üblich sendet - ist das ein Signal zur Überprüfung.

Du kannst einen Alarm einstellen: Einstellungen → Benachrichtigungen → Alarm, wenn tägliche Credits > X.

Authentifizierungsfehler

Code	Bedeutung
401 Unauthorized	Header X-Api-Key fehlt oder Schlüssel ist ungültig
403 Forbidden	Schlüssel ist gültig, hat aber keinen Scope für diese Aktion (z.B. ein normaler Schlüssel versucht, andere Schlüssel zu verwalten)
403 PUBLISHABLE_KEY_UNBOUNDED	pk_-Schlüssel ohne Budget credits_cap_cycle oder ohne Bereich allowed_endpoints: Lege beides in den Schlüsseleinstellungen fest
402 Payment Required	Credits aufgebraucht (im Free-Plan) oder Abonnement inaktiv
429 Too Many Requests	Rate Limit überschritten (10/60/300 Anfragen/Min je nach Plan)

Beispiel 401:

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

Sandbox-Modus

Schlüssel mit dem Präfix aw_test_ funktionieren in der Sandbox:

• Buchen keine Credits ab
• Geben eine Stub- oder minimale reale Antwort zurück
• Beeinflussen die Produktionsstatistik nicht
• Verfügbare Endpunkte: dieselben

Nützlich für CI/CD, E2E-Tests und lokale Entwicklung. Wird über das Dashboard mit einem Klick erstellt.

Weiter

• Credits und Limits: wie Abrechnung und Rate Limiting funktionieren
• Fehler: vollständige Liste der Fehlercodes