Authentication

AstroAPI supports multiple authentication methods depending on your use case.

API Key Authentication

API keys are the recommended method for server-to-server communication.

Obtaining an API Key

1. Log in to the AstroAPI Dashboard
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Configure permissions and rate limits
5. Copy the generated key (it won't be shown again)

Using API Keys

Include your API key in the X-Api-Key header:

curl -X GET "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: ak_live_xxxxxxxxxxxx"

API Key Permissions

API keys can be scoped to specific permissions:

Permission	Description
calc:read	Access calculation endpoints
content:read	Access content/interpretation endpoints
chart:read	Access chart rendering endpoints
modules:read	Access purchased modules

Organization Context

For multi-tenant applications, API keys are scoped to organizations. The organization context is automatically applied based on the API key used.

Domain Restrictions

API keys can be configured with domain restrictions to limit which websites can use them:

• example.com - Exact domain match
• *.example.com - All subdomains
• * - Allow all domains (not recommended)

Configure domain restrictions in the dashboard when creating or editing an API key.

Important Limitation

Domain restrictions only protect against browser-based abuse. They rely on the Origin and Referer headers, which browsers enforce but can be easily spoofed outside the browser (e.g., curl, scripts, server-side code).

Client-Side vs Server-Side Usage

Server-to-Server (Recommended)

For production applications, always use API keys on your backend server:

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│   Browser   │ ───► │  Your Backend   │ ───► │  AstroAPI   │
│  (no keys)  │      │  (API key here) │      │             │
└─────────────┘      └─────────────────┘      └─────────────┘

This approach:

• Keeps your API key secure and hidden
• Allows you to add your own authentication layer
• Prevents API key extraction by end users
• Enables request signing and additional security measures

Client-Side / Browser Usage

If you must use API keys directly in the browser (e.g., embedded widgets on static sites), be aware of the limitations:

• API keys are visible in JavaScript source code and network requests
• Anyone can extract the key from your website
• Domain restrictions only prevent other websites from using your key via JavaScript - they do not prevent someone from copying the key and using it elsewhere

For client-side usage, we recommend:

• Enable domain restrictions
• Set strict rate limits
• Use short expiration times
• Monitor usage for anomalies

Customer Responsibility

Important

You are responsible for the security and usage of your API keys.

All API requests made with your API key count against your quota and are billed to your account, regardless of whether the requests were made by you or by someone who obtained your key.

If you expose an API key in client-side code and it gets misused, you are responsible for the resulting usage and costs. AstroAPI cannot distinguish between legitimate requests and unauthorized requests made with a valid API key.

To minimize risk:

1. Use server-to-server communication whenever possible
2. Never commit API keys to version control
3. Rotate keys immediately if you suspect they have been compromised
4. Set up usage alerts to detect unexpected spikes

Security Best Practices

• Use server-to-server communication for production applications
• Never expose API keys in client-side code unless absolutely necessary
• Rotate API keys periodically
• Use the minimum required permissions
• Enable domain restrictions for client-side keys
• Set appropriate rate limits
• Monitor API key usage in the dashboard