# Kimlik doğrulama

AstroWay API'ye yapılan neredeyse tüm istekler `X-Api-Key` başlığı aracılığıyla doğrulanır. İstisnalar: 14 adet `/v1/reference/*` uç noktası (burçlar, gezegenler, evler, açılar, …) anahtar olmadan, IP başına saatte 30 istek sınırlamasıyla herkese açık olarak çalışır. İstekler sunucunuz tarafından yapılıyorsa, `X-AstroWay-Site-URL` başlığını gönderin ve limit site başına saatte 300 isteğe yükselir: [ayrıntılar](/rate-limits-credits/#sunucu-taraflı-işleme-kotası).

 Tüm **hesaplama uç noktaları `/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` aracılığıyla verilen Bearer JWT. Herkese açık API'de OAuth/oturum çerezleri kullanılmaz. **Referans sözlükleri `/v1/reference/*`** - anahtarsız, ücretsiz (kanonik arama tabloları).

## Anahtar Formatı

```
aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
```

- `aw_live_`: üretim, bakiyeden kredi düşer
- `aw_test_`: sandbox, istekler sabit bir yanıt (veya minimum gerçek hesaplama) döndürür, **kredi düşmez**, kontrol panelinde ayrı olarak işaretlenir
- Ön ekten sonra: 48 onaltılık karakter, kriptografik olarak rastgele
- Anahtar **yalnızca bir kez** açık metin olarak gösterilir: oluşturulurken veya güncellenirken. Yalnızca SHA-256'sını saklarız, bu nedenle anahtarı ikinci kez göstermek mümkün değildir, yalnızca güncellenebilir. Kontrol panelinde yalnızca ön ek ve son 4 karakter görünür.
- Google, GitHub, tek kullanımlık kod veya siparişle giriş yapıldığında oluşturulan anahtarı henüz kimse görmemiştir. Kontrol panelinde yanında "Anahtarı Göster" düğmesi bulunur: bu düğme aynı sınıftan yeni bir anahtarı bir kez verir.

## İstek Başlığı

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

## Postman Koleksiyonu

Eğer curl/SDK yerine Postman senin için daha uygunsa - tüm 865 uç noktalarını içeren, OpenAPI etiketlerine göre 55 klasöre ayrılmış, örnek isteklerle birlikte hazır bir koleksiyon bulunmaktadır. Kimlik doğrulama koleksiyon düzeyinde ayarlanmıştır: anahtarı `apiKey` değişkenine bir kez eklersin, tüm istekler bunu kullanır.

- **Yayınlanmış belgeler:** [documenter.getpostman.com/view/54689779/2sBXqNmy3n](https://documenter.getpostman.com/view/54689779/2sBXqNmy3n)
- **Herkese açık çalışma alanı:** [postman.com/astroway-info/astroway-api](https://www.postman.com/astroway-info/astroway-api)
- **JSON indir:** [astroway-api.json](/postman/astroway-api.json) (≈ 5 MB) - doğrudan Postman veya Insomnia'ya aktar
Koleksiyon [OpenAPI spec](https://api.astroway.info/v1/openapi.json) üzerinden otomatik olarak oluşturulur - her dağıtımda güncellenir.

## Anahtar Oluşturma ve Yönetimi

Kontrol paneli üzerinden:
- [api.astroway.info/dashboard/keys](https://api.astroway.info/dashboard/keys)
- Hesap başına aynı anda **10 adede kadar aktif anahtar** olabilir
- Her anahtarın bir adı, `name` alanı vardır (örneğin `production-backend`, `ci-tests`, `local-dev`)

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

  **cURL**
    ```bash frame="terminal"
    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**
    ```ts
    // 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**
    ```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
    <?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:**
Ana anahtar (kontrol panelinde oluşturduğun), `/v1/keys` aracılığıyla diğer anahtarları yönetebilir. Normal anahtarlar yönetemez. Bu, anahtarın `scope`'unda belirtilmiştir.

## Tarayıcı Anahtarları

Tipik bir anahtar **server-only**'dir: eğer onunla yapılan bir istek `Origin` veya
`Referer` başlığı taşıyorsa, `403 ORIGIN_FORBIDDEN` yanıtı gelir. Bu kasıtlıdır ve ön uçta
yanlışlıkla bırakılan bir anahtarı yakalamak içindir. Tek istisna: Kontrol panelindeki
Playground ve belgelerdeki "Dene" düğmeleri herhangi bir anahtarla çalışır.

Bir widget veya sayfa tarayıcıdan API'ye istek göndermesi gerektiğinde, anahtar
hemen bir kaynak politikasıyla oluşturulur. `POST /v1/keys` içindeki `origin_restriction` alanı:

| `tür` | İzin Verilenler | Ne Zaman Kullanılır |
|---|---|---|
| `server-only` (varsayılan) | yalnızca `Origin` ve `Referer` içermeyen istekler | arka uç, cron, CI |
| `public` | yalnızca listelenen ana bilgisayarlar ve istek **kaynak taşımak zorundadır** | **alan adınızdaki widget veya sayfa**, kaynak kodundaki anahtar |
| `allowlist` | `public` ile aynı | eski yazım: hala kabul edilir, ancak `openapi.json`'da artık yer almaz |

```bash frame="terminal"
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/*"]
  }'
```

Üretimde test edilmiş eşleştirme kuralları:

- Anahtar başına **20** adede kadar ana bilgisayar. Şema (`https://`) ve bağlantı noktası göz ardı edilir, büyük/küçük harf duyarlı değildir.
- `www.` gelen ana bilgisayardan kaldırılır, bu nedenle `example.com` hem
  `example.com`'u hem de `www.example.com`'u kapsar. **`www.` içeren formu ayrıca
  eklemeye gerek yoktur**, hiçbir şeyi değiştirmez.
- `*.example.com` alt alan adlarını (`app.example.com`) kapsar, ancak **`example.com`'un kendisini kapsamaz**. Apex, yukarıdaki örnekte olduğu gibi ayrı bir satırda listelenir.
- Listedeki olmayan bir ana bilgisayar, hangi satırın eksik olduğunu görmek için
  `incoming_origin` alanında ana bilgisayarın kendisiyle birlikte `403 ORIGIN_NOT_ALLOWED` alır.
- `Referer`, `Origin` ile aynı düzeyde sayılır: tarayıcı, `Origin`'in olmadığı yerlerde onu gönderir.

**Caution:**
`type: "public"` `pk_` sınıfından bir anahtar oluşturur ve onun için kural terstir: `Origin` ve `Referer` içermeyen bir istek `403 ORIGIN_REQUIRED` alır, sunucu isteği olarak geçmez. Bu nedenle oluşturulurken üç şey zorunludur: alan adları listesi, `credits_cap_cycle` bütçesi ve `allowed_endpoints` kapsamı (her ikisi de aşağıda açıklanmıştır). Bunlardan herhangi biri olmadan `400` yanıtı gelir ve bütçesi veya kapsamı eksik olan `pk_` anahtarı her yerde `403 PUBLISHABLE_KEY_UNBOUNDED` ile reddedilir. Sayfa kodundaki anahtarı herkes okuyabilir, bu yüzden asla sınırsız olmaz. 2026-09-12 tarihine kadar bu mod "herhangi bir kaynak" anlamına geliyordu; 2026-09-24 tarihinde bu tür son anahtarlar kendi trafiklerinden toplanan bir liste aldı veya tarayıcı istekleri yoksa sunucu anahtarı oldular. `pk_` anahtarının listesindeki Origin, `/v1/*` yanıtlarında `access-control-allow-origin` da alır, böylece sayfa bunları okuyabilir. Politika, `GET /v1/keys` içinde `origin_restriction` alanında görülebilir.

### Zaten Oluşturulmuş Bir Anahtarın Listesini Değiştirme

`PATCH /v1/keys/{id}` anahtarın kendisine dokunmadan listeyi yeniden yazar. Erişim hakkı yukarıdaki `POST /v1/keys` ile aynıdır; kontrol panelinde bu, anahtar menüsündeki "Kaynağı Değiştir" öğesidir.

```bash frame="terminal"
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 sıfırlanır, bir dakika beklemeye gerek yoktur. Anahtar dizisi değişmez, bu nedenle ne sayfayı ne de arka ucu yeniden yayınlamaya gerek yoktur. `POST /v1/keys/{id}/rotate` işleminden sonra liste korunur ve eski anahtar değeri hemen çalışmayı durdurur.

Anahtar sınıfı düzenlenemez, çünkü anahtarın kendisinde yazılıdır:

| Deneme | Yanıt |
|---|---|
| `pk_`'yi `server-only` yapmak | `400`: sınıf anahtarın bir parçasıdır, iptal edip yeni bir tane oluşturmak gerekir |
| `aw_`'ye alan adları listesi vermek | `400`: tarayıcı anahtarı farklı bir sınıftır, `public` olarak oluşturulur |
| `pk_` boş liste ile | `400`: listesiz bir anahtar her isteği reddederdi |
| `pk_` bütçe veya kapsam olmadan (`null`) | `400`: tarayıcı anahtarı her zaman her ikisiyle de sınırlıdır, değiştirilebilir ancak kaldırılamaz |

### Ayrı Bir Anahtar İçin Kredi Bütçesi

Krediler tüm hesap için ortaktır, bu nedenle bir anahtar hepsini harcayabilir. Arka uç anahtarı için bu normaldir, ancak sayfanın kaynak kodundaki bir anahtar için değildir: alan adları listesi nereden erişilebileceğini söyler, ancak bunun ne kadara mal olabileceğini söylemez.

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

```bash frame="terminal"
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` kısıtlamayı kaldırır (`pk_` anahtarı hariç, onun bütçesi değiştirilebilir ancak kaldırılamaz). `0` hiçbir şey harcayamayan bir anahtar anlamına gelir: anahtarı iptal etmeden park etme yöntemi. Sayıcı kredilerle aynıdır ve tarife döngüsüyle birlikte sıfırlanır.

Anahtar kendi bütçesine ulaştığında, hesapta hala kredi kalsa bile ve hatta aşım içeren bir tarifede bile `429 KEY_BUDGET_EXHAUSTED` yanıtı gelir: parayla aşılabilecek bir bütçe, gerçek bir bütçe değildir. Bütçe belirlendiği sürece, her yanıt `X-Key-Budget-Limit` ve `X-Key-Budget-Remaining` başlıklarını taşır.

### Uç Nokta Kapsamı

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

```bash frame="terminal"
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` kısıtlamayı kaldırır (`pk_` anahtarı hariç, onun kapsamı zorunludur). Boş liste kabul edilmez: hem "her şey" hem de "hiçbir şey" olarak okunurdu. Yollar `/v1`'e göre, başlangıç eğik çizgisi olmadan yazılır, büyük/küçük harf duyarlı değildir.

Liste dışı bir çağrı `403 ENDPOINT_NOT_IN_SCOPE` alır ve `details` tahmin etmek zorunda kalmamak için listenin kendisini belirtir. Kapsam her iki anahtar sınıfı için de geçerlidir ve `/v1/public/*` ile `/v1/embed/*` üzerinde de diğerleri gibi etkilidir. Kredilerin aksine, hizmet okumaları bundan **muaf değildir**: `embed/*` ile daraltılmış bir anahtar kendi istatistiklerini bile okuyamaz. Bu kasıtlıdır, çünkü sayfanın kaynak kodundaki bir anahtar ziyaretçiye hesap harcamalarını vermemelidir ve bu, anahtarı yönetmeyi engellemez: kontrol paneli bir oturumla, anahtarla değil, çalışır.

## En İyi Uygulamalar

### 1. Yalnızca Sunucu Anahtarını Ön Uca Koyma

Tipik bir anahtar arka uç düzeyinde bir sırdır. Kullanıcının tarayıcısında çalışan JS'ye düşerse - DevTools'ta görünür ve sızar. Bu nedenle böyle bir anahtar, `Origin` veya `Referer` içeren herhangi bir isteğe `403 ORIGIN_FORBIDDEN` ile yanıt verir.

Yine de tarayıcıdan erişmek gerekiyorsa, bu normal bir anahtarla değil, `origin_restriction.type: "public"` ile oluşturulmuş ayrı bir anahtarla yapılır: [tarayıcı anahtarları](#tarayıcı-anahtarları). Böyle bir anahtar `pk_` ön ekine sahiptir, o da DevTools'ta görünür ve tüm mesele budur - değeri alan adlarınızın listesiyle sınırlıdır ve kaynak içermeyen bir isteği reddeder.

**Doğru:** kendi arka ucun anahtarı tutar, ön uç senin arka ucuna, senin arka ucun ise AstroWay API'ye istek gönderir.

**Yanlış:**

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

### 2. Ortam Değişkenleri, Sabit Kodlama Değil

```bash
# .env (in .gitignore)
ASTROWAY_API_KEY=aw_live_...
```

```ts
// in code
const key = process.env.ASTROWAY_API_KEY;
if (!key) throw new Error('ASTROWAY_API_KEY is not set');
```

### 3. Farklı Ortamlar İçin Ayrı Anahtarlar

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

Bir anahtar tehlikeye atılırsa - yalnızca onu iptal et, diğerleri çalışmaya devam eder.

### 4. Rotasyon

Önerilen sıklık - **90 günde bir**. Veya bir sızıntı şüphesi varsa derhal.

Kesinti olmadan rotasyon:
1. Aynı `name` + `-v2` ile yeni bir anahtar oluştur
2. Üretime dağıt (eskiyle paralel olarak)
3. Kullanımın yeni anahtara aktığını doğrula (kontrol paneli)
4. Eskiyi iptal et

### 5. Kullanım İzleme

Kontrol paneli, anahtarlara göre istekleri ayrı ayrı gösterir. Eğer aniden bir anahtar normalden 10 kat daha fazla istek yapmaya başlarsa - bu bir kontrol sinyalidir.

Bir uyarı ayarlayabilirsin: `Ayarlar → Bildirimler → Günlük krediler X'ten büyük olduğunda uyar`.

## Kimlik Doğrulama Hataları

| Kod | Anlamı |
|---|---|
| `401 Unauthorized` | `X-Api-Key` başlığı eksik veya anahtar geçersiz |
| `403 Forbidden` | Anahtar geçerli, ancak bu eylem için kapsamı yok (örneğin, normal bir anahtar diğer anahtarları yönetmeye çalışıyor) |
| `403 PUBLISHABLE_KEY_UNBOUNDED` | `pk_` anahtarı `credits_cap_cycle` bütçesi veya `allowed_endpoints` kapsamı olmadan: her ikisini de anahtar ayarlarında belirt |
| `402 Payment Required` | Krediler bitti (Ücretsiz planda) veya abonelik aktif değil |
| `429 Too Many Requests` | Hız limiti aşıldı (plana bağlı olarak 10/60/300 istek/dakika) |

`401` örneği:

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

## Sandbox Modu

`aw_test_` ön ekli anahtarlar sandbox'ta çalışır:

- Kredi düşmez
- Sabit veya minimum gerçek yanıt döndürür
- Üretim istatistiklerini etkilemez
- Mevcut uç noktalar: aynıları

CI/CD, e2e testleri ve yerel geliştirme için kullanışlıdır. Kontrol paneli üzerinden tek tıklamayla oluşturulur.

## Sonraki Adımlar

- [Krediler ve Limitler](/rate-limits-credits/): faturalandırma ve hız sınırlamasının nasıl çalıştığı
- [Hatalar](/errors/): hata kodlarının tam listesi
