Authentication

Almost all AstroWay API requests authenticate via the X-Api-Key header. Exceptions: the 14 /v1/reference/* endpoints (signs, planets, houses, aspects, …) are public — no key required, capped at 30 requests / hour per IP.

No other methods — no OAuth, JWT, or session cookies at the API level. Reference dictionaries /v1/reference/* are public and free (canonical lookup tables).

Key format

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_ — production, deducts credits from balance
aw_test_ — sandbox, returns stub responses (or minimal real calculations), does not consume credits, tracked separately in dashboard
After the prefix: 32 base62 characters, cryptographically random
Key is shown in plain text only once at creation. Dashboard shows only first and last 4 characters afterward.

Request header

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

Postman collection

If Postman is more convenient than curl/SDK — there’s a ready-made collection with all 705 endpoints, grouped into 55 folders by OpenAPI tag, with example bodies pre-filled. Auth is configured at collection level: paste your key into the apiKey variable once and every request picks it up.

Published docs: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Public workspace: postman.com/astroway-info/astroway-api
Download JSON: astroway-api.json (≈ 5 MB)
Run in Postman:

The collection is auto-generated from the OpenAPI spec — refreshed on every deploy.

Creating and managing keys

Via dashboard:

api.astroway.info/dashboard/keys
Up to 10 active keys per account at once
Each key has a label (e.g. production-backend, ci-tests, local-dev)

Via API (for self-service integrations):

curl -X POST https://api.astroway.info/v1/keys \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-tests", "mode": "test"}'

// Equivalent via @astroway/sdk: aw.client.POST('/keys', { body: { label, 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({ label: 'ci-tests', mode: 'test' }),
});

const { data: created } = await r.json();
console.log(created.key); // shown once — store it now

# Equivalent via `astroway` (PyPI): aw.post('/keys', body={'label': ..., 'mode': ...})
import os, requests

r = requests.post(
    'https://api.astroway.info/v1/keys',
    headers={'X-Api-Key': os.environ['ASTROWAY_MASTER_KEY']},
    json={'label': 'ci-tests', 'mode': 'test'},
)
created = r.json()['data']
print(created['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' => ['label' => 'ci-tests', 'mode' => 'test'],
]);

$created = json_decode($r->getBody(), true);
echo $created['key']; // shown once — store it now

Best practices

1. Never put the key in frontend

The key is a backend-level secret. If it lands in JS that runs in the user’s browser — it’s visible in DevTools and will leak.

Correct: your backend holds the key, frontend calls your backend, your backend calls AstroWay API.

Incorrect:

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

2. Environment variables, not 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. Separate keys per environment

production-backend — production
staging-backend — staging
ci-tests — CI/CD pipeline
local-dev-alice — local development per developer

If one key is compromised — revoke just that one, others keep working.

4. Rotation

Recommended frequency — every 90 days. Or immediately on suspected leak.

Zero-downtime rotation:

Create a new key with the same label + -v2
Deploy it to production (in parallel with old one)
Confirm traffic flows to new key (dashboard)
Revoke the old one

5. Monitor usage

Dashboard shows requests per key separately. If one key suddenly starts making 10× more requests than usual — investigate.

Set an alert: Settings → Notifications → Alert when daily credits > X.

Authentication errors

Code	Meaning
`401 Unauthorized`	`X-Api-Key` header missing or key invalid
`403 Forbidden`	Key valid but lacks scope (e.g. regular key managing other keys)
`402 Payment Required`	Credits exhausted (Free) or subscription inactive
`429 Too Many Requests`	Rate limit exceeded (10/60/300 req/min per plan)

Example 401:

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