🌍 Astrocartography API and ✋ Palmistry API are now live. Ship them in your app today.Get Started

Guides

Access tokens vs. User ID and API key

AstrologyAPI supports two ways to authenticate a request: a wallet access token, or a User ID and API key pair. Both are valid. This guide compares them and explains why a new project should default to an access token.

Compare the two credentials

Both credentials live on the same Credentials page in your dashboard.

Access tokenUser ID + API key
What it isA single token tied to your account, also called a Wallet Access Token.A key pair issued alongside a subscribed plan.
How it authenticatesAn x-astrologyapi-key header, with a JSON request body.HTTP Basic auth: your User ID as the username, your API key as the password, with a form-encoded body.
What it can callWallet-based APIs (for example moon_biorhythm) and the Chat APIs.Subscription endpoints for the plan the key belongs to.
Where it's createdThe Credentials page in your dashboard (New access token).Issued with each subscription plan you purchase, and listed on the same Credentials page.
How it's billedPay-as-you-go, drawn from your wallet balance.Tied to the subscribed plan's billing. It stops authenticating if the plan expires or is cancelled.

How each request looks

Both examples call western_horoscope, the same endpoint the access token guide uses. Only the auth and the body encoding change.

With an access token

Send the token in an x-astrologyapi-key header, and send the body as JSON.

curl --location 'https://json.astrologyapi.com/v1/western_horoscope' \
  --header 'Content-Type: application/json' \
  --header 'x-astrologyapi-key: <YOUR_ACCESS_TOKEN>' \
  --data '{
    "day": 12,
    "month": 3,
    "year": 1993,
    "hour": 14,
    "min": 15,
    "lat": 19.076,
    "lon": 72.8777,
    "tzone": 5.5,
    "house_type": "placidus",
    "is_asteroids": "false"
}'

With a User ID and API key

Send the User ID and API key as HTTP Basic auth credentials, and send the body as form-encoded fields.

curl --location 'https://json.astrologyapi.com/v1/western_horoscope' \
  --user '<YOUR_USER_ID>:<YOUR_API_KEY>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'day=12' \
  --data-urlencode 'month=3' \
  --data-urlencode 'year=1993' \
  --data-urlencode 'hour=14' \
  --data-urlencode 'min=15' \
  --data-urlencode 'lat=19.076' \
  --data-urlencode 'lon=72.8777' \
  --data-urlencode 'tzone=5.5' \
  --data-urlencode 'house_type=placidus' \
  --data-urlencode 'is_asteroids=false'
Both endpoints reject requests sent directly from a browser (CORS), so route every call through your server. Never put an API key or an access token in client-side code. See the access token usage guide for the client-facing pattern.

Why tokens for new projects

  • No subscription required. A token draws pay-as-you-go from your wallet balance. A User ID and API key pair only exists once you've subscribed to a plan.
  • One credential, one balance. A single token covers every wallet-based endpoint from one balance. Each API key is scoped to one subscribed plan, so more suites means more key pairs to track.
  • Created and revoked from the dashboard. Create, rotate, or delete a token from the Credentials page. Rotating a compromised token doesn't touch your subscription keys.
  • Powers the Chat APIs with the same header. The same x-astrologyapi-key header that authenticates wallet-based APIs also authenticates the Chat APIs.
  • Can mint an MCP token without a subscription. The dashboard's MCP token screen accepts a wallet token as its source credential, so you can connect an MCP client like Claude, Cursor, ChatGPT, or Windsurf without an active subscription plan.

When User ID and API key still makes sense

If you already have an active subscription plan with a fixed monthly volume, the API key you already have keeps working. It only calls the endpoints under that plan, so it isn't a fit for wallet-based APIs, the Chat APIs, or MCP. Compare plans on the pricing page before you decide.

Where to go next