Kimlik doğrulama

AstroWay API’ye yapılan isteklerin neredeyse tamamı X-Api-Key başlığıyla kimlik doğrular. İstisnalar: 14 adet /v1/reference/* endpoint’i (signs, planets, houses, aspects, …) anahtarsız, herkese açık olarak, IP başına saatte 30 istek sınırıyla çalışır. İstekleri sunucunuz yapıyorsa X-AstroWay-Site-URL başlığını gönderin, sınır site başına saatte 300 isteğe çıkar: ayrıntılar.

60 saniyede API anahtarı al

aw_test_demo_aaaa1111

Ücretsiz kaydol→

Tüm hesaplama endpoint’leri /v1/* (chart, synastry, transits, /reports, /tarot vb.) için yalnızca X-Api-Key. Kullanıcı işlemleri /v1/me/* (GET /me, DELETE /me/account) için /v1/auth/login üzerinden verilen Bearer JWT. Herkese açık API’de OAuth/oturum çerezleri kullanılmaz. Başvuru sözlükleri /v1/reference/*: anahtarsız, ücretsiz (kanonik arama tabloları).

Anahtar biçimi

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

• aw_live_: production, bakiyeden kredi düşer
• aw_test_: sandbox, istekler stub bir yanıt (veya minimal gerçek bir hesaplama) döndürür, kredi düşmez, panelde ayrıca işaretlenir
• Önekten sonra: kriptografik olarak rastgele 32 base62 karakter
• Anahtar açık hâliyle oluşturma sırasında yalnızca bir kez gösterilir. Sonrasında panelde yalnızca ilk ve son 4 karakteri görünür.

İstek başlığı

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

Postman koleksiyonu

Postman size curl/SDK’dan daha rahat geliyorsa, 771 endpoint’in tamamını içeren, OpenAPI etiketlerine göre 55 klasöre ayrılmış ve örnek istekleri doldurulmuş hazır bir koleksiyon var. Kimlik doğrulama koleksiyon düzeyinde ayarlanmıştır: anahtarı apiKey değişkenine bir kez yapıştırırsınız, tüm istekler onu kullanır.

• Yayınlanmış dokümantasyon: documenter.getpostman.com/view/54689779/2sBXqNmy3n
• Herkese açık çalışma alanı: postman.com/astroway-info/astroway-api
• JSON’u indirin: astroway-api.json (≈ 5 MB): doğrudan Postman’e veya Insomnia’ya içe aktarın

Koleksiyon OpenAPI spesifikasyonundan otomatik üretilir ve her deploy ile güncellenir.

Anahtar oluşturma ve yönetme

Panel üzerinden:

• api.astroway.info/dashboard/keys
• Hesap başına aynı anda 10 aktif anahtara kadar sahip olabilirsiniz
• Her anahtarın bir adı vardır, name alanı (örneğin production-backend, ci-tests, local-dev)

API üzerinden (self-service entegrasyonlar için):

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

İpucu

Master anahtar (panelde oluşturduğunuz anahtar) /v1/keys üzerinden diğer anahtarları yönetebilir. Normal anahtarlar bunu yapamaz. Bu, anahtarın scope alanında tanımlıdır.

Tarayıcı için anahtarlar

Varsayılan anahtar server-only’dir: onunla yapılan bir istek Origin veya Referer başlığı taşıyorsa 403 ORIGIN_FORBIDDEN gelir. Bu bilinçli bir tercihtir ve frontend’de yanlışlıkla bırakılmış bir anahtarı yakalayan şey budur.

Bir widget’ın veya sayfanın tarayıcıdan API’ye erişmesi gerektiğinde, anahtar baştan bir köken politikasıyla oluşturulur. POST /v1/keys içindeki origin_restriction alanı:

type	Neye izin verilir	Ne zaman kullanılır
server-only (varsayılan)	yalnızca Origin ve Referer içermeyen istekler	backend, cron, CI
public	yalnızca listelenen host’lar ve istek bir köken taşımak zorundadır	alan adınızdaki bir widget veya sayfa, anahtar kaynak kodda
allowlist	public ile aynı	eski yazım: kabul edilmeye devam eder, ancak artık openapi.json içinde yer almaz

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

Üretim ortamında doğrulanmış eşleştirme kuralları:

• Anahtar başına en fazla 20 host. Şema (https://) ve port yok sayılır, büyük/küçük harf fark etmez.
• Gelen host’tan www. çıkarılır, yani example.com aynı zamanda www.example.com’u da kapsar. www. biçimini ayrıca eklemeniz gerekmez, hiçbir şeyi değiştirmez.
• *.example.com alt alan adlarını (app.example.com) kapsar, ancak example.com’un kendisini kapsamaz. Kök alan adı, yukarıdaki örnekte olduğu gibi ayrı bir satır olarak listelenir.
• Listede olmayan bir host, hangi satırın eksik olduğu görülsün diye incoming_origin alanında host’un kendisiyle birlikte 403 ORIGIN_NOT_ALLOWED alır.
• Referer, Origin ile eşit sayılır: tarayıcı onu Origin’in olmadığı yerlerde gönderir.

Dikkat

type: "public" pk_ sınıfı bir anahtar oluşturur ve onun için kural terstir: Origin ve Referer içermeyen bir istek sunucu isteği olarak geçmez, 403 ORIGIN_REQUIRED alır. Bu yüzden liste oluşturma sırasında zorunludur, aksi hâlde 400 gelir. 2026-09-12’ye kadar bu mod “herhangi bir origin” anlamına geliyordu; 2026-09-24’te bu tür son anahtarlar kendi trafiklerinden derlenmiş bir liste aldı ya da hiç tarayıcı isteği yoksa sunucu anahtarına dönüştürüldü. pk_ anahtarının listesindeki bir origin, /v1/* yanıtlarında access-control-allow-origin de alır, böylece sayfa bunları okuyabilir. Politika GET /v1/keys içinde origin_restriction alanında görünür.

Oluşturulmuş bir anahtarın listesini değiştirme

PATCH /v1/keys/{id} anahtarın kendisine dokunmadan listeyi yeniden yazar. Erişim yetkisi yukarıdaki POST /v1/keys ile aynıdır; panelde bu, anahtar menüsündeki “Kökeni değiştir” öğesidir.

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

Yeni liste bir sonraki istekten itibaren geçerlidir: anahtar önbelleği yazma sırasında temizlenir, bir dakika beklemeye gerek yoktur. Anahtar dizesinin kendisi değişmez, yani ne sayfayı ne de backend’i yeniden yayınlamak gerekir. POST /v1/keys/{id}/rotate sonrasında liste korunur ve anahtarın eski değeri hemen çalışmayı durdurur.

Anahtarın sınıfı düzenlenemez, çünkü anahtarın kendisine yazılmıştır:

Deneme	Yanıt
pk_’yi server-only yapmak	400: sınıf anahtarın bir parçasıdır, iptal edip yenisini oluşturmak gerekir
aw_’ye alan adı listesi vermek	400: tarayıcı anahtarı başka bir sınıftır, public olarak oluşturulur
boş listeli pk_	400: listesiz bir anahtar her isteği reddederdi

Tek bir anahtar için kredi bütçesi

Krediler tüm hesap için ortaktır, yani tek bir anahtar hepsini harcayabilir. Bir backend anahtarı için bu normaldir, sayfanın kaynak kodundaki bir anahtar için değil: alan adı listesi nereden erişilebileceğini söyler, ama bunun kaça mal olabileceğini söylemez.

Aynı PATCH /v1/keys/{id} içindeki credits_cap_cycle tam olarak bu anahtarı sınırlar:

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 sınırı kaldırır. 0, hiçbir şey harcanamayan bir anahtar demektir: bir anahtarı iptal etmeden park etmenin yolu. Sayaç kredilerinkiyle aynıdır ve plan döngüsüyle birlikte sıfırlanır.

Bir anahtar kendi bütçesine dayandığında, hesapta hâlâ kredi kalmış olsa bile ve overage içeren bir planda bile 429 KEY_BUDGET_EXHAUSTED gelir: parayla aşılabilen bir bütçe bütçe değildir. Bütçe tanımlı olduğu sürece her yanıt X-Key-Budget-Limit ve X-Key-Budget-Remaining taşır.

Endpoint kapsamı

Kapsamı olmayan bir anahtar plana dahil olan her şeyi çağırır. allowed_endpoints onu bir yol listesine daraltır: tam bir yol (chart) veya bir ad alanı (embed/*). Bu üçüncü, bağımsız bir kısıtlamadır: alan adı listesi nereden, bütçe ne kadar, kapsam tam olarak neyi söyler.

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 sınırı kaldırır. Boş liste kabul edilmez: hem “her şey” hem de “hiçbir şey” olarak okunabilirdi. Yollar /v1’e göre, başta eğik çizgi olmadan yazılır, büyük/küçük harf önemli değildir.

Listenin dışındaki bir çağrı 403 ENDPOINT_NOT_IN_SCOPE alır ve tahmin etmek zorunda kalmamanız için details listenin kendisini belirtir. Kapsam her iki anahtar sınıfı için de geçerlidir ve /v1/public/* ile /v1/embed/* üzerinde de diğerlerinde olduğu gibi çalışır. Kredilerden farklı olarak, hizmet okumaları bu kapsamdan muaf değildir: embed/* ile daraltılmış bir anahtar kendi istatistiklerini bile okuyamaz. Bu bilinçlidir, çünkü sayfanın kaynak kodundaki bir anahtar ziyaretçiye hesabın harcamalarını vermemelidir; anahtarı yönetmeye ise engel olmaz: panel anahtarla değil, oturumla çalışır.

En iyi uygulamalar

1. Server-only anahtarı frontend’e koymayın

Varsayılan anahtar backend düzeyinde bir sırdır. Kullanıcının tarayıcısında çalışan JS’e girerse, DevTools’ta görünür ve sızar. İşte bu yüzden böyle bir anahtar, Origin veya Referer içeren her isteğe 403 ORIGIN_FORBIDDEN ile yanıt verir.

Tarayıcıdan erişmek yine de gerekiyorsa, bu normal bir anahtarla değil, origin_restriction.type: "public" ile oluşturulmuş ayrı bir anahtarla yapılır: tarayıcı için anahtarlar. Böyle bir anahtarın öneki pk_’dir, o da DevTools’ta görünür ve bütün mesele budur: değeri alan adlarınızın listesiyle sınırlıdır ve kökeni olmayan bir isteği reddeder.

Doğru: anahtarı kendi backend’iniz tutar, frontend backend’inize, backend’iniz de AstroWay API’ye istek atar.

Yanlış:

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

2. Hardcode değil, ortam değişkenleri

# .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. Farklı ortamlar için ayrı anahtarlar

• production-backend: production
• staging-backend: staging
• ci-tests: CI/CD pipeline
• local-dev-maksym: her geliştiricinin yerel geliştirmesi

Bir anahtar ele geçirilirse yalnızca onu iptal edin, diğerleri çalışmaya devam eder.

4. Döndürme

Önerilen sıklık 90 günde birdir. Ya da bir sızıntı şüphesi varsa hemen.

Kesintisiz döndürme:

1. Aynı name + -v2 ile yeni bir anahtar oluşturun
2. Onu production’a dağıtın (eskisiyle paralel olarak)
3. Kullanımın yeni anahtara aktığından emin olun (panel)
4. Eskisini iptal edin

5. Kullanım izleme

Panel istekleri anahtar bazında ayrı ayrı gösterir. Bir anahtar birdenbire her zamankinden 10× fazla istek yapmaya başlarsa, bu kontrol etmek için bir sinyaldir.

Bir uyarı kurabilirsiniz: Settings → Notifications → Alert when daily credits > X.

Kimlik doğrulama hataları

Kod	Anlamı
401 Unauthorized	X-Api-Key başlığı yok veya anahtar geçersiz
403 Forbidden	Anahtar geçerli, ancak bu işlem için scope’u yok (örneğin, normal bir anahtar diğer anahtarları yönetmeye çalışıyor)
402 Payment Required	Krediler bitti (Free’de) veya abonelik aktif değil
429 Too Many Requests	Rate limit aşıldı (plana bağlı olarak 10/60/300 req/min)

401 örneği:

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

Sandbox modu

aw_test_ önekli anahtarlar sandbox’ta çalışır:

• Kredi düşmez
• Stub veya minimal gerçek bir yanıt döndürür
• Production istatistiklerini etkilemez
• Kullanılabilir endpoint’ler: aynıları

CI/CD, e2e testleri ve yerel geliştirme için kullanışlıdır. Panelden tek tıkla oluşturulur.

Sonraki adımlar

• Krediler ve limitler: faturalandırma ve rate limiting nasıl çalışır
• Hatalar: hata kodlarının tam listesi