認証

AstroWay APIへのほとんどすべてのリクエストは、X-Api-Key ヘッダーを介して認証されます。例外として、14の /v1/reference/* エンドポイント（signs, planets, houses, aspects, …）は、キーなしで公開されており、IPアドレスごとに1時間あたり30リクエストの制限があります。あなたのサーバーがリクエストを行う場合、X-AstroWay-Site-URL ヘッダーを送信すると、サイトごとに1時間あたり300リクエストに制限が緩和されます：詳細。

すべての計算エンドポイント /v1/*（chart, synastry, transits, /reports, /tarotなど）には、X-Api-Key のみが必要です。ユーザー操作 /v1/me/*（GET /me, DELETE /me/account）には、/v1/auth/login を介して発行されたBearer JWTが必要です。公開APIではOAuth/セッションクッキーは使用されません。リファレンス辞書 /v1/reference/* はキーなしで無料です（標準的なルックアップテーブル）。

キーの形式

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: 本番環境、残高からクレジットを消費します
aw_test_: サンドボックス、リクエストはスタブ応答（または最小限の実際の計算）を返します。クレジットは消費されません。ダッシュボードで個別にマークされます。
プレフィックスの後：32文字のbase62、暗号学的にランダム
キーは作成時に一度だけプレーンテキストで表示されます。その後、ダッシュボードでは最初の4文字と最後の4文字のみが表示されます。

リクエストヘッダー

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

Postmanコレクション

curl/SDKよりもPostmanの方が使いやすい場合は、すべての771エンドポイントを含む準備されたコレクションがあります。これはOpenAPIタグごとに55のフォルダーに再分割されており、リクエストの例が設定されています。認証はコレクションレベルで設定されています。apiKey 変数にキーを一度入力するだけで、すべてのリクエストがそれを引き継ぎます。

公開ドキュメント: documenter.getpostman.com/view/54689779/2sBXqNmy3n
公開ワークスペース: postman.com/astroway-info/astroway-api
JSONをダウンロード: astroway-api.json (≈ 5 MB) - PostmanまたはInsomniaに直接インポートしてください。

コレクションはOpenAPI specから自動生成され、デプロイごとに更新されます。

キーの作成と管理

ダッシュボード経由：

api.astroway.info/dashboard/keys
アカウントごとに最大10個のアクティブなキーを同時に持つことができます。
各キーには名前、name フィールドがあります（例：production-backend, ci-tests, local-dev）。

API経由（セルフサービス統合用）：

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

ブラウザ用キー

標準のキーはサーバー専用です。そのキーを含むリクエストが Origin または Referer ヘッダーを伴う場合、403 ORIGIN_FORBIDDEN が返されます。これは意図的なものであり、フロントエンドに誤って残されたキーを捕捉するためのものです。

ウィジェットやページがブラウザからAPIにアクセスする必要がある場合、キーはすぐにオリジンポリシー付きで作成されます。POST /v1/keys の origin_restriction フィールド：

`type`	許可されるもの	使用する場面
`server-only` (デフォルト)	`Origin` と `Referer` のないリクエストのみ	バックエンド、cron、CI
`public`	リストされたホストのみ、かつリクエストは必ずオリジンを伴う	あなたのドメイン上のウィジェットやページ、ソースコード内のキー
`allowlist`	`public` と同じ	非推奨の表記：引き続き受け入れられますが、`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/*"]
  }'

本番環境で検証済みのマッチングルール：

キーごとに最大20のホスト。スキーム（https://）とポートは無視され、大文字小文字は区別されません。
www. は入力ホストから削除されるため、example.com は www.example.com もカバーします。www. を含む形式を別途追加する必要はありません。何も変わりません。
*.example.com はサブドメイン（app.example.com）をカバーしますが、example.com 自体はカバーしません。上記の例のように、エイペックスは別の行でリストされます。
リストにないホストは、incoming_origin フィールドにそのホスト自体を含む 403 ORIGIN_NOT_ALLOWED を受け取ります。これにより、どの行が不足しているかを確認できます。
Referer は Origin と同等に扱われます。ブラウザは Origin がない場合に Referer を送信します。

type: "public" は pk_ クラスのキーを作成し、そのルールは逆になります。Origin も Referer もないリクエストは、サーバーリクエストとして通過するのではなく、403 ORIGIN_REQUIRED を受け取ります。したがって、作成時には3つのことが必須です：ドメインのリスト、credits_cap_cycle の予算、および allowed_endpoints のスコープ（両方とも以下で説明）。いずれかが欠けている場合、400 が返され、予算またはスコープが不足している pk_ キーは、403 PUBLISHABLE_KEY_UNBOUNDED とともにどこでも拒否されます。ページコード内のキーは誰でも読み取れるため、無制限になることはありません。 2026-09-12までは、このモードは「任意のオリジン」を意味していました。2026-09-24には、最後のそのようなキーが自身のトラフィックから収集されたリストを受け取るか、ブラウザリクエストがなかった場合はサーバーキーになりました。pk_ キーのリストにあるオリジンは、/v1/* の応答で access-control-allow-origin も受け取るため、ページはそれらを読み取ることができます。ポリシーは GET /v1/keys の origin_restriction フィールドで確認できます。

既存のキーのリストを変更する

PATCH /v1/keys/{id} は、キー自体に触れることなくリストを上書きします。アクセス権は上記の POST /v1/keys と同じです。ダッシュボードでは、キーメニューの「オリジンを変更」項目です。

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

新しいリストは次のリクエストから有効になります。キーのキャッシュは書き込み時にリセットされるため、1分待つ必要はありません。キー文字列自体は変更されないため、ページもバックエンドも再発行する必要はありません。POST /v1/keys/{id}/rotate の後、リストは保持され、古いキー値はすぐに機能しなくなります。

キーのクラスは、キー自体に記録されているため編集できません：

試行	応答
`pk_` を `server-only` にする	`400`：クラスはキーの一部であり、取り消して新しいものを作成する必要があります
`aw_` にドメインリストを与える	`400`：ブラウザキーは別のクラスであり、`public` として作成されます
`pk_` を空のリストにする	`400`：リストのないキーはすべてのリクエストを拒否します
`pk_` を予算またはスコープなし（`null`）にする	`400`：ブラウザ用キーは常に両方で制限されており、変更はできますが削除はできません

個別キーのクレジット予算

クレジットはアカウント全体で共有されるため、1つのキーがすべてを使い果たす可能性があります。バックエンドキーではこれは問題ありませんが、ページソースコード内のキーではそうではありません。ドメインリストはどこからアクセスできるかを伝えますが、それがどれくらいの費用がかかるかは伝えません。

同じ PATCH /v1/keys/{id} の credits_cap_cycle は、このキーを制限します：

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 は制限を解除します（pk_ キーを除く。その予算は変更できますが、解除はできません）。0 は何も消費できないキーを意味します。これは、キーを取り消さずに一時停止する方法です。カウンターはクレジットと同じで、料金プランのサイクルとともにリセットされます。

キーが予算に達すると、アカウントにクレジットが残っていても、超過料金プランであっても 429 KEY_BUDGET_EXHAUSTED が返されます。お金を払って超過できる予算は、予算ではありません。予算が設定されている間、すべての応答には X-Key-Budget-Limit と X-Key-Budget-Remaining が含まれます。

エンドポイントのスコープ

スコープのないキーは、料金プランに含まれるすべてを呼び出します。allowed_endpoints は、それをパスのリストに絞り込みます。正確なパス（chart）または名前空間（embed/*）です。これは3番目の独立した制限です。ドメインリストはどこから、予算はいくら、スコープは何を、を伝えます。

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 は制限を解除します（pk_ キーを除く。そのスコープは必須です）。空のリストは受け入れられません。それは「すべて」とも「何もない」とも解釈されるためです。パスは /v1 から相対的に記述され、先頭のスラッシュは不要で、大文字小文字は区別されません。

リスト外の呼び出しは 403 ENDPOINT_NOT_IN_SCOPE を受け取り、details にはリスト自体が示されるため、推測する必要はありません。スコープは両方のキーのクラス、および /v1/public/* と /v1/embed/* にも、他のものと同様に適用されます。クレジットとは異なり、その下でのサービス読み取りは免除されません。embed/* に絞られたキーは、自身の統計情報も読み取れません。これは意図的なものです。ページソースコード内のキーは、訪問者にアカウントの費用を公開すべきではなく、キーの管理を妨げるものではありません。ダッシュボードはキーではなくセッションでアクセスします。

ベストプラクティス

1. サーバー専用キーをフロントエンドに置かない

標準のキーはバックエンドレベルの秘密です。それがユーザーのブラウザで実行されるJSに入り込むと、DevToolsで見えてしまい、漏洩します。まさにそのため、そのようなキーは Origin または Referer を含むあらゆるリクエストに対して 403 ORIGIN_FORBIDDEN を返します。

ブラウザからアクセスする必要がある場合は、通常のキーではなく、origin_restriction.type: "public" で作成された別のキーを使用します：ブラウザ用キー。そのようなキーは pk_ というプレフィックスを持ち、DevToolsでも見えます。そして、それがすべてです。その価値はあなたのドメインのリストに制限されており、オリジンのないリクエストは拒否します。

正しい方法: あなたのバックエンドがキーを保持し、フロントエンドがあなたのバックエンドにアクセスし、あなたのバックエンドがAstroWay APIにアクセスします。

間違った方法:

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

2. 環境変数を使用し、ハードコードしない

# .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. 環境ごとに異なるキーを使用する

production-backend: 本番環境
staging-backend: ステージング環境
ci-tests: CI/CDパイプライン
local-dev-maksym: 各開発者のローカル開発

1つのキーが侵害された場合、そのキーのみを取り消し、他のキーは引き続き機能します。

4. ローテーション

推奨頻度は90日に1回です。または、漏洩の疑いがある場合は直ちに。

ダウンタイムなしのローテーション：

同じ name + -v2 で新しいキーを作成します。
それを本番環境にデプロイします（古いキーと並行して）。
使用状況が新しいキーに流れていることを確認します（ダッシュボード）。
古いキーを取り消します。

5. 使用状況の監視

ダッシュボードはキーごとのリクエストを個別に表示します。もし突然1つのキーが通常より10倍多くのリクエストを始めた場合、それは確認すべき兆候です。

アラートを設定できます：Settings → Notifications → Alert when daily credits > X。

認証エラー

コード	意味
`401 Unauthorized`	`X-Api-Key` ヘッダーがないか、キーが無効です
`403 Forbidden`	キーは有効ですが、このアクションのスコープがありません（例：通常のキーが他のキーを管理しようとしている）
`403 PUBLISHABLE_KEY_UNBOUNDED`	`credits_cap_cycle` の予算または `allowed_endpoints` のスコープがない `pk_` キー：キー設定で両方を設定してください
`402 Payment Required`	クレジットがなくなりました（無料プランの場合）またはサブスクリプションが非アクティブです
`429 Too Many Requests`	レート制限を超過しました（プランに応じて1分あたり10/60/300リクエスト）

401 の例：

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