Autentikasi

Hampir semua permintaan ke AstroWay API diautentikasi melalui header X-Api-Key. Pengecualian: 14 endpoint /v1/reference/* (signs, planets, houses, aspects, …) berfungsi secara publik tanpa kunci dengan batasan 30 permintaan/jam per IP. Jika permintaan dibuat oleh server kamu, kirimkan header X-AstroWay-Site-URL dan batasnya akan menjadi 300 permintaan/jam per situs: detail.

Untuk semua endpoint komputasi /v1/* (chart, synastry, transits, /reports, /tarot, dll.) - hanya X-Api-Key. Untuk operasi pengguna /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, yang dikeluarkan melalui /v1/auth/login. OAuth/session-cookies tidak digunakan pada API publik. Kamus referensi /v1/reference/* - tanpa kunci, gratis (tabel pencarian kanonik).

Format Kunci

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: produksi, memotong kredit dari saldo
aw_test_: sandbox, permintaan mengembalikan respons stub (atau perhitungan nyata minimal), tidak memotong kredit, ditandai secara terpisah di dashboard
Setelah prefiks: 48 karakter heksadesimal, acak secara kriptografis
Kunci ditampilkan dalam bentuk teks biasa hanya sekali: saat dibuat atau diperbarui. Kami hanya menyimpan SHA-256-nya, jadi kunci tidak dapat ditampilkan lagi, hanya dapat diperbarui. Selanjutnya di dashboard, hanya prefiks dan 4 karakter terakhir yang terlihat.
Kunci yang dibuat saat masuk melalui Google, GitHub, kode satu kali, atau dari pesanan, belum pernah dilihat oleh siapa pun. Di dashboard, ada tombol “Tampilkan kunci” di sampingnya: ini akan mengeluarkan kunci baru dari kelas yang sama sekali.

Header Permintaan

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

Postman collection

Jika Postman lebih nyaman bagimu daripada curl/SDK - ada collection siap pakai dengan semua 771 endpoint, dibagi lagi menjadi 55 folder berdasarkan tag OpenAPI, dengan contoh permintaan yang sudah diisi. Autentikasi diatur pada tingkat collection: kamu cukup memasukkan kunci ke variabel apiKey sekali, dan semua permintaan akan menggunakannya.

Dokumen yang Diterbitkan: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Ruang Kerja Publik: postman.com/astroway-info/astroway-api
Unduh JSON: astroway-api.json (≈ 5 MB) - impor langsung ke Postman atau Insomnia

Collection dibuat secara otomatis dari Spesifikasi OpenAPI - diperbarui dengan setiap deployment.

Pembuatan dan Pengelolaan Kunci

Melalui dashboard:

api.astroway.info/dashboard/keys
Kamu dapat memiliki hingga 10 kunci aktif per akun secara bersamaan
Setiap kunci memiliki nama, bidang name (misalnya production-backend, ci-tests, local-dev)

Melalui API (untuk integrasi self-service):

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

Kunci untuk Browser

Kunci tipikal adalah server-only: jika permintaan dengannya membawa header Origin atau Referer, akan ada 403 ORIGIN_FORBIDDEN. Ini disengaja, dan inilah yang menangkap kunci yang secara tidak sengaja tertinggal di frontend.

Ketika widget atau halaman harus memanggil API dari browser, kunci dibuat langsung dengan kebijakan asal. Bidang origin_restriction di POST /v1/keys:

`type`	Apa yang diizinkan	Kapan digunakan
`server-only` (default)	hanya permintaan tanpa `Origin` dan `Referer`	backend, cron, CI
`public`	hanya host yang terdaftar, dan permintaan wajib membawa asal	widget atau halaman di domain kamu, kunci di kode sumber
`allowlist`	sama dengan `public`	penulisan usang: masih diterima, tetapi tidak lagi tercantum di `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/*"]
  }'

Aturan pencocokan, diverifikasi di produksi:

Hingga 20 host per kunci. Skema (https://) dan port diabaikan, case-insensitivity.
www. dihapus dari host yang masuk, jadi example.com mencakup juga www.example.com. Tidak perlu menambahkan formulir dengan www. secara terpisah, itu tidak mengubah apa pun.
*.example.com mencakup subdomain (app.example.com), tetapi bukan example.com itu sendiri. Apex terdaftar sebagai baris terpisah, seperti contoh di atas.
Host yang tidak ada dalam daftar akan menerima 403 ORIGIN_NOT_ALLOWED dengan host itu sendiri di bidang incoming_origin, agar terlihat baris mana yang hilang.
Referer dihitung setara dengan Origin: browser mengirimkannya di mana Origin tidak ada.

type: "public" membuat kunci kelas pk_, dan untuk itu aturannya terbalik: permintaan tanpa Origin dan tanpa Referer menerima 403 ORIGIN_REQUIRED, dan tidak lolos sebagai server-only. Oleh karena itu, saat membuat, tiga hal wajib: daftar domain, anggaran credits_cap_cycle, dan cakupan allowed_endpoints (keduanya dijelaskan di bawah). Tanpa salah satunya, akan ada 400, dan kunci pk_ yang kekurangan anggaran atau cakupan, akan ditolak di mana-mana dengan 403 PUBLISHABLE_KEY_UNBOUNDED. Kunci dalam kode halaman dapat dibaca oleh siapa saja, jadi tidak pernah tanpa batas. Hingga 2026-09-12, mode ini berarti “origin apa pun”; 2026-09-24 kunci terakhir seperti itu menerima daftar yang dikumpulkan dari lalu lintas mereka sendiri, atau menjadi server-only jika tidak memiliki permintaan browser. Origin dari daftar kunci pk_ juga menerima access-control-allow-origin dalam respons /v1/*, sehingga halaman dapat membacanya. Kebijakan terlihat di GET /v1/keys di bidang origin_restriction.

Mengubah Daftar untuk Kunci yang Sudah Dibuat

PATCH /v1/keys/{id} menimpa daftar tanpa menyentuh kunci itu sendiri. Hak aksesnya sama dengan POST /v1/keys di atas; di dashboard ini adalah item “Ubah asal” di menu kunci.

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

Daftar baru berlaku segera setelah permintaan berikutnya: cache kunci direset saat penulisan, tidak perlu menunggu satu menit. String kunci itu sendiri tidak berubah, jadi tidak perlu menerbitkan ulang halaman atau backend. Setelah POST /v1/keys/{id}/rotate, daftar disimpan, dan nilai kunci lama segera berhenti berfungsi.

Kelas kunci tidak dapat diedit, karena sudah tertulis di kunci itu sendiri:

Percobaan	Respons
`pk_` menjadi `server-only`	`400`: kelas adalah bagian dari kunci, perlu dicabut dan dibuat yang baru
`aw_` diberi daftar domain	`400`: kunci browser adalah kelas yang berbeda, dibuat sebagai `public`
`pk_` dengan daftar kosong	`400`: kunci tanpa daftar akan menolak setiap permintaan
`pk_` tanpa anggaran atau cakupan (`null`)	`400`: kunci untuk browser selalu dibatasi oleh keduanya, dapat diubah, tetapi tidak dapat dihapus

Anggaran Kredit per Kunci

Kredit bersifat umum untuk seluruh akun, jadi satu kunci dapat menghabiskan semuanya. Untuk kunci backend ini normal, untuk kunci di kode sumber halaman tidak: daftar domain memberi tahu dari mana dapat diakses, tetapi tidak memberi tahu berapa biayanya.

credits_cap_cycle di PATCH /v1/keys/{id} yang sama membatasi kunci ini:

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 menghapus batasan (kecuali untuk kunci pk_, anggarannya dapat diubah, tetapi tidak dapat dihapus). 0 berarti kunci yang tidak dapat menghabiskan apa pun: cara untuk memarkir kunci tanpa mencabutnya. Penghitungnya sama dengan kredit, dan direset bersama dengan siklus tarif.

Ketika kunci mencapai anggarannya, akan ada 429 KEY_BUDGET_EXHAUSTED, bahkan jika masih ada kredit di akun, dan bahkan pada tarif dengan overage: anggaran yang dapat dihabiskan dengan uang bukanlah anggaran. Selama anggaran ditentukan, setiap respons membawa X-Key-Budget-Limit dan X-Key-Budget-Remaining.

Cakupan Endpoint

Kunci tanpa cakupan memanggil semua yang termasuk dalam tarif. allowed_endpoints mempersempitnya ke daftar jalur: tepat (chart) atau namespace (embed/*). Ini adalah batasan ketiga yang independen: daftar domain memberi tahu dari mana, anggaran berapa banyak, cakupan apa tepatnya.

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 menghapus batasan (kecuali untuk kunci pk_, cakupannya wajib). Daftar kosong tidak diterima: akan dibaca sebagai “semua” dan “tidak ada” secara bersamaan. Jalur ditulis relatif terhadap /v1, tanpa garis miring awal, case-insensitivity.

Panggilan di luar daftar akan menerima 403 ENDPOINT_NOT_IN_SCOPE, dan details akan menyebutkan daftar itu sendiri agar tidak perlu menebak. Cakupan berlaku untuk kedua kelas kunci dan untuk /v1/public/* serta /v1/embed/* sama seperti yang lainnya. Pembacaan layanan dari bawahnya tidak dikecualikan, tidak seperti kredit: kunci yang dipersempit ke embed/* tidak akan membaca statistiknya sendiri. Ini disengaja, karena kunci di kode sumber halaman tidak boleh memberikan biaya akun kepada pengunjung, dan ini tidak menghalangi pengelolaan kunci: dashboard diakses dengan sesi, bukan kunci.

Praktik Terbaik

1. Jangan Letakkan Kunci Server-Only di Frontend

Kunci tipikal adalah rahasia tingkat backend. Jika masuk ke JS yang dieksekusi di browser pengguna - akan terlihat di DevTools dan akan bocor. Itulah mengapa kunci semacam itu merespons 403 ORIGIN_FORBIDDEN untuk setiap permintaan dengan Origin atau Referer.

Jika akses dari browser tetap diperlukan, ini dilakukan bukan dengan kunci biasa, melainkan dengan kunci terpisah, yang dibuat dengan origin_restriction.type: "public": kunci untuk browser. Kunci semacam itu memiliki prefiks pk_, juga terlihat di DevTools, dan inilah intinya - nilainya dibatasi oleh daftar domain kamu, dan permintaan tanpa asal akan ditolaknya.

Benar: backend kamu menyimpan kunci, frontend memanggil backend kamu, backend kamu - ke AstroWay API.

Salah:

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

2. Variabel Lingkungan, Bukan 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. Kunci Terpisah untuk Lingkungan Berbeda

production-backend: produksi
staging-backend: staging
ci-tests: pipeline CI/CD
local-dev-maksym: pengembangan lokal setiap pengembang

Jika satu kunci dikompromikan - cabut kunci itu saja, yang lain tetap berfungsi.

4. Rotasi

Frekuensi yang direkomendasikan adalah sekali setiap 90 hari. Atau segera, jika ada dugaan kebocoran.

Rotasi tanpa downtime:

Buat kunci baru dengan name yang sama + -v2
Deploy ke produksi (secara paralel dengan yang lama)
Pastikan penggunaan mengalir ke kunci baru (dashboard)
Cabut yang lama

5. Pemantauan Penggunaan

Dashboard menampilkan permintaan berdasarkan kunci secara terpisah. Jika tiba-tiba satu kunci mulai membuat 10× lebih banyak permintaan dari biasanya - ini adalah sinyal untuk diperiksa.

Kamu bisa mengatur peringatan: Settings → Notifications → Alert when daily credits > X.

Kesalahan Autentikasi

Kode	Arti
`401 Unauthorized`	Header `X-Api-Key` tidak ada atau kunci tidak valid
`403 Forbidden`	Kunci valid, tetapi tidak memiliki cakupan untuk tindakan ini (misalnya, kunci biasa mencoba mengelola kunci lain)
`403 PUBLISHABLE_KEY_UNBOUNDED`	Kunci `pk_` tanpa anggaran `credits_cap_cycle` atau tanpa cakupan `allowed_endpoints`: atur keduanya di pengaturan kunci
`402 Payment Required`	Kredit habis (di Free) atau langganan tidak aktif
`429 Too Many Requests`	Batas laju terlampaui (10/60/300 req/menit tergantung paket)

Contoh 401:

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

Mode Sandbox

Kunci dengan prefiks aw_test_ berfungsi di sandbox:

Tidak memotong kredit
Mengembalikan respons stub atau respons nyata minimal
Tidak memengaruhi statistik produksi
Endpoint yang tersedia: sama

Berguna untuk CI/CD, tes e2e, dan pengembangan lokal. Dibuat melalui dashboard dengan satu klik.

Selanjutnya

Kredit dan Batasan: cara kerja penagihan dan pembatasan laju
Kesalahan: daftar lengkap kode kesalahan

Bermanfaat?

Usulkan perbaikan

Terakhir diperbaharui: 16 Okt 2026