Authentication and API Keys

AstroAPI deliberately separates calculation credentials from dashboard sessions. API keys authorize server-to-server calculations; a protected browser session authorizes account-management routes.

API keys

Every /api/astro/* endpoint requires one 64-character hexadecimal API key. Send it using the preferred Bearer header:

Authorization: Bearer YOUR_API_KEY

The equivalent header below is also supported:

x-api-key: YOUR_API_KEY

Key lifecycle

• An account currently has one active key at a time.
• The dashboard returns plaintext only when a key is generated or regenerated.
• The database stores only a one-way SHA-256 digest, so the existing plaintext cannot be displayed again.
• Regeneration revokes every prior active key before creating the replacement.
• Generating or rotating a key requires your current account password.
• Password change or recovery revokes the active key; create a replacement after signing in again.
• Rotate immediately after suspected exposure; multi-key project scopes are planned, not available.

Server-side request

curl https://api.astroapi.io/api/astro/birth-chart \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ASTROAPI_KEY" \
  -d '{
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 0,
    "lon": 0
  }'

Dashboard sessions

After email verification, dashboard login creates an eight-hour server-side session and sets its signed credential in a Secure, HttpOnly, SameSite cookie. The login response does not expose that credential to JavaScript, and AstroAPI does not store it in localStorage. Dashboard requests send the cookie automatically; protected account changes also carry exact approved-origin evidence and AstroAPI's request marker. This session is not accepted by calculation endpoints. Logout, password change, and password reset revoke database-backed sessions. Five failed current-password confirmations revoke only the session making those attempts; the account itself is not locked, so its owner can sign in normally.

Login endpoint

POST https://api.astroapi.io/auth/login

{
  "email": "user@example.com",
  "password": "your-password",
  "turnstileToken": "TOKEN_FROM_THE_LOGIN_WIDGET"
}

Production login and signup both require a single-use Cloudflare Turnstile result bound to the correct widget action and AstroAPI hostname. Use the hosted login form for dashboard access; API integrations should authenticate calculation requests with an API key.

Login response

{
  "user": {
    "id": "8dd9b117-803a-4571-9d09-998c8a799682",
    "email": "user@example.com",
    "first_name": "Example",
    "last_name": "Developer",
    "plan": "free"
  }
}

Account protection

• At least 12 characters and no more than 72 UTF-8 bytes
• At least one letter and one number
• A valid Cloudflare Turnstile verification from the signup or login form
• Email ownership must be verified before login or API-key use

New registration may be temporarily closed during deployment or maintenance. When it is open, signup returns a generic response and sends an expiring verification link when the address is eligible; it does not start a dashboard session immediately.

Authentication errors

• 400 invalid signup, verification, reset, or password-policy input
• 401 missing, malformed, revoked, or unknown API key; invalid dashboard credentials or session
• 403 unverified email, disallowed browser mutation, or failed login/signup bot verification
• 429 quota, per-user concurrency, or edge rate/connection limit
• 503 closed registration or authentication concurrency/dependency failure; retry only when appropriate