ऑथेंटिकेशन

लगभग सभी अनुरोध AstroWay API को header X-Api-Key के माध्यम से प्रमाणित किया जाता है। अपवाद: 14 एंडपॉइंट /v1/reference/* (signs, planets, houses, aspects, …) सार्वजनिक रूप से बिना कुंजी के काम करते हैं, प्रति IP 30 अनुरोध/घंटा की सीमा के साथ। अगर अनुरोध तुम्हारा सर्वर करता है, तो header X-AstroWay-Site-URL भेजो और सीमा साइट पर 300 अनुरोध/घंटा हो जाएगी: विवरण.

सभी गणनात्मक एंडपॉइंट /v1/* (chart, synastry, transits, /reports, /tarot आदि) - केवल X-Api-Key। उपयोगकर्ता ऑपरेशन्स /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, जो /v1/auth/login से जारी होता है। सार्वजनिक API पर OAuth/session-cookies उपयोग नहीं होते। Reference-डिक्शनरी /v1/reference/* - बिना कुंजी के, मुफ्त (मानक lookup-टेबल)।

कुंजी का फ़ॉर्मेट

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_: production, बैलेंस से क्रेडिट घटाता है
aw_test_: sandbox, अनुरोध स्थिर प्रतिक्रिया (या न्यूनतम वास्तविक गणना) लौटाते हैं, क्रेडिट नहीं घटाते, dashboard में अलग से चिह्नित
प्रीफ़िक्स के बाद: 32 अक्षर base62, क्रिप्टोग्राफ़िक रूप से रैंडम
कुंजी को साफ़ रूप में सिर्फ एक बार निर्माण के समय दिखाया जाता है। बाद में dashboard में - केवल पहले और आखिरी 4 अक्षर।

अनुरोध हेडर

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

Postman कलेक्शन

अगर तुम्हें Postman curl/SDK से ज़्यादा सुविधाजनक लगता है - एक तैयार कलेक्शन है जिसमें सभी 771 एंडपॉइंट्स हैं, OpenAPI टैग्स के अनुसार 55 फ़ोल्डरों में विभाजित, और अनुरोध उदाहरणों के साथ। Auth कलेक्शन स्तर पर सेट है: apiKey वैरिएबल में कुंजी एक बार डालो, सभी अनुरोध इसे ले लेंगे।

Published docs: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Public workspace: 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 के माध्यम से (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

ब्राउज़र के लिए कुंजियाँ

डिफ़ॉल्ट कुंजी server-only: अगर अनुरोध में 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 दोनों example.com और www.example.com को कवर करता है। अलग से www. जोड़ने की ज़रूरत नहीं, यह कुछ नहीं बदलता।
*.example.com सबडोमेन्स (app.example.com) को कवर करता है, लेकिन स्वयं example.com को नहीं। एपीक्स को अलग लाइन में सूचीबद्ध किया जाता है, जैसा ऊपर के उदाहरण में।
सूची में नहीं होने वाला होस्ट 403 ORIGIN_NOT_ALLOWED के साथ incoming_origin फ़ील्ड में स्वयं होस्ट लौटाता है, ताकि पता चले कौन सी लाइन गायब है।
Referer को Origin के बराबर माना जाता है: ब्राउज़र इसे तब भेजता है जब Origin नहीं होता।

type: "public" एक कुंजी क्लास pk_ बनाता है, और इसके लिए नियम उल्टा है: Origin और Referer बिना वाला अनुरोध 403 ORIGIN_REQUIRED प्राप्त करता है, और सर्वर जैसा नहीं चलता। इसलिए निर्माण के समय तीन चीज़ें अनिवार्य हैं: डोमेन सूची, बजट credits_cap_cycle और क्षेत्र allowed_endpoints (दोनों नीचे वर्णित)। इनमें से कोई भी नहीं होने पर 400 मिलता है, और कुंजी pk_ जो बजट या क्षेत्र की कमी रखती है, हर जगह 403 PUBLISHABLE_KEY_UNBOUNDED के साथ अस्वीकृत होती है। पेज के कोड में कुंजी को हर कोई पढ़ सकता है, इसलिए वह कभी अनलिमिटेड नहीं होती। 2026-09-12 तक यह मोड “कोई भी origin” दर्शाता था; 2026-09-24 को अंतिम ऐसे कुंजियों को उनके स्वयं के ट्रैफ़िक से बनाई गई सूची मिली, या यदि ब्राउज़र अनुरोध नहीं थे तो वे सर्वर बन गए। pk_ कुंजी की सूची से origin भी /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"]
    }
  }'

नई सूची अगले अनुरोध से प्रभावी होती है: कुंजी का कैश लिखते समय रीसेट हो जाता है, एक मिनट इंतजार नहीं करना पड़ता। कुंजी की स्ट्रिंग नहीं बदलती, इसलिए पेज या बैकएंड को फिर से रिलीज़ करने की ज़रूरत नहीं। POST /v1/keys/{id}/rotate के बाद सूची सहेजी जाती है, और पुराना कुंजी मान तुरंत काम करना बंद कर देता है।

कुंजी का क्लास नहीं बदला जा सकता, क्योंकि वह स्वयं कुंजी में एन्कोडेड है:

प्रयास	उत्तर
`pk_` को `server-only` बनाना	`400`: क्लास कुंजी का हिस्सा है, इसे रिवोक करके नई बनानी पड़ेगी
`aw_` को डोमेन सूची देना	`400`: ब्राउज़र कुंजी अलग क्लास है, यह `public` के रूप में बनती है
`pk_` को खाली सूची के साथ	`400`: सूची बिना कुंजी हर अनुरोध को अस्वीकार कर देगा
`pk_` बिना बजट या क्षेत्र (`null`)	`400`: ब्राउज़र कुंजी हमेशा दोनों से सीमित रहती है, उन्हें बदला जा सकता है, लेकिन हटाया नहीं जा सकता

एकल कुंजी के लिए क्रेडिट बजट

क्रेडिट पूरे अकाउंट में साझा होते हैं, इसलिए एक कुंजी सभी खर्च कर सकती है। बैकएंड कुंजी के लिए यह सामान्य है, लेकिन पेज के सोर्स कोड में कुंजी के लिए नहीं: डोमेन सूची बताती है कहां से कॉल किया जा सकता है, लेकिन यह नहीं बताती कि कितना खर्च होगा।

credits_cap_cycle उसी PATCH /v1/keys/{id} में इस कुंजी को सीमित करता है:

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/*)। यह तीसरी, स्वतंत्र सीमा है: डोमेन सूची कहती है कहां से, बजट कहता है कितना, क्षेत्र बताता है क्या।

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. server-only कुंजी को फ्रंटएंड में न रखें

डिफ़ॉल्ट कुंजी बैकएंड स्तर का सीक्रेट है। अगर यह यूज़र के ब्राउज़र में चलने वाले 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. Environment variables, 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. विभिन्न वातावरणों के लिए अलग-अलग कुंजियाँ

production-backend: प्रोडक्शन
staging-backend: स्टेजिंग
ci-tests: CI/CD पाइपलाइन
local-dev-maksym: प्रत्येक डेवलपर की स्थानीय विकास

अगर कोई कुंजी समझौता हो गई है - केवल उसे रिवोक करो, बाकी काम करना जारी रखेंगे।

4. रोटेशन

सिफ़ारिश की गई आवृत्ति - हर 90 दिन। या तुरंत, अगर लीक का संदेह हो।

डाउntime के बिना रोटेशन:

वही name + -v2 के साथ नई कुंजी बनाओ
इसे प्रोड में डिप्लॉय करो (पुरानी के साथ समानांतर)
सुनिश्चित करो कि usage नया कुंजी पर जा रहा है (dashboard)
पुरानी को रिवोक करो

5. उपयोग की निगरानी

डैशबोर्ड प्रत्येक कुंजी के अनुरोध अलग-अलग दिखाता है। अगर अचानक कोई कुंजी सामान्य से 10× अधिक अनुरोध करता है - यह जांच का संकेत है।

एक अलर्ट सेट किया जा सकता है: Settings → Notifications → Alert when daily credits > X.

प्रमाणीकरण त्रुटियाँ

कोड	विवरण
`401 Unauthorized`	Header `X-Api-Key` अनुपस्थित या कुंजी अमान्य
`403 Forbidden`	कुंजी वैध है, लेकिन इस कार्रवाई के लिए scope नहीं है (उदाहरण: सामान्य कुंजी अन्य कुंजियों को नियंत्रित करने की कोशिश करती है)
`403 PUBLISHABLE_KEY_UNBOUNDED`	कुंजी `pk_` के पास `credits_cap_cycle` बजट या `allowed_endpoints` क्षेत्र नहीं है: दोनों को कुंजी सेटिंग्स में सेट करें
`402 Payment Required`	क्रेडिट समाप्त हो गए (Free पर) या सब्सक्रिप्शन सक्रिय नहीं
`429 Too Many Requests`	rate limit पार हो गया (10/60/300 req/min योजना के अनुसार)

उदाहरण 401:

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

Sandbox मोड

प्रिफिक्स aw_test_ वाली कुंजियाँ sandbox में काम करती हैं:

क्रेडिट नहीं घटाते
स्थिर या न्यूनतम वास्तविक प्रतिक्रिया लौटाते हैं
प्रोडक्शन की आँकड़ों को प्रभावित नहीं करते
उपलब्ध एंडपॉइंट्स: वही

CI/CD, e2e टेस्ट और स्थानीय विकास के लिए उपयोगी। डैशबोर्ड से एक क्लिक में बनाया जाता है।

आगे

क्रेडिट और लिमिट्स: बिलिंग और rate limiting कैसे काम करता है
त्रुटियाँ: error कोड की पूरी सूची

उपयोगी रहा?

संपादन सुझाएं

आखिरी अद्यतन: 5 अक्टू॰ 2026