Authentication

API Authentication

All API requests require authentication via an API key. Include your key in thex-api-keyheader with every request.

Get Your API Key

Visit our pricing page and choose a plan
Choose a subscription plan that fits your needs
Navigate to your Dashboard
Your API key will be displayed in the API Key section

FreeAstroAPI Overview

Watch the short setup walkthrough, then use the examples below to make your first authenticated request.

Base URL

https://api.freeastroapi.com

Required Headers

Header	Value	Required
x-api-key	Your API key	Yes
Content-Type	application/json	Yes (for POST)
Idempotency-Key	Client-generated unique operation key	No (recommended for billable POST retries)

Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept Idempotency-Key: <client-generated unique operation key>. Generate one key per intended operation. Reuse the same key only when retrying the exact same request after a timeout or network failure.

Node.js

const idempotencyKey = crypto.randomUUID();

await fetch("https://api.freeastroapi.com/api/v1/natal/calculate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.FREE_ASTRO_API_KEY,
    "Idempotency-Key": idempotencyKey
  },
  body: JSON.stringify(payload)
});

Python

import uuid

idempotency_key = str(uuid.uuid4())

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
    "Idempotency-Key": idempotency_key
}

Authentication Examples

curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year": 1990, "month": 5, "day": 15, "hour": 10, "minute": 30, "city": "New York", "lat": 40.7128, "lng": -74.006}'

Security Best Practices

•Never expose your API key in client-side code. Make API calls from your backend server.
•Use environment variables to store your API key, not hardcoded strings.
•Rotate your API key if you suspect it has been compromised.
•Monitor your usage in the dashboard to detect unusual activity.

Authentication Errors

Status	Message	Description
401	Missing API key	x-api-key header not provided
401	Invalid API key	The API key does not exist or was revoked
429	Rate limit exceeded	You've exceeded your plan's request limit
403	Subscription required	Your subscription has expired or is inactive

Rate Limits

Rate limits vary by subscription plan. The following headers are included in every response:

Header	Description
X-RateLimit-Limit	Total requests allowed per period
X-RateLimit-Remaining	Requests remaining in current period
X-RateLimit-Reset	Timestamp when the limit resets

Next Steps

Natal Chart (Western)

Calculate your first natal chart

Vedic Chart

Explore Vedic astrology endpoints