API keys and authentication for astrology APIs

The Vedika astrology API authenticates every request with a single secret key sent in the x-api-key header. Production keys use the vk_live_ prefix; enterprise keys use vk_ent_. There is no OAuth handshake, no token exchange, and no per-endpoint credential to manage. This guide walks through getting a key, sending it correctly, securing it, debugging the failures you will actually hit, and testing for free before you spend a cent.

How authentication works

Authentication is header-based and stateless. You attach your key to each HTTPS request, and the gateway resolves it to your account, plan, and wallet balance before routing the call. That single key both proves who you are and tells the billing system which wallet to debit, so there is nothing to refresh between requests and no session to keep alive.

Every call goes over TLS to https://api.vedika.io. Keys are never accepted as query-string parameters, because URLs are logged by proxies, browsers, and CDNs; the header keeps the secret out of those logs.

Key formats at a glance

Getting your first key

Keys are issued per account from the dashboard once you choose a plan. Plans start at $12/month for Starter and scale through Professional, Business, and Enterprise, with per-query costs typically landing between $0.01 and $0.05 depending on the endpoint and whether you use the fast path. The wallet model means your key draws against prepaid credits, so a leaked key has a bounded financial blast radius equal to your remaining balance plus any auto-top-up you have configured.

1. Pick a plan on the pricing page and create your account.
2. Open the dashboard and generate a vk_live_ key. Copy it immediately; the full secret is shown once.
3. Store it in a secret manager or environment variable, never in source control.
4. Make a first authenticated call to confirm the key is active.

Making your first authenticated request

The flagship endpoint is the AI query at POST /api/v1/astrology/query. It takes a natural-language question plus a birthDetails object and returns an interpreted answer. Here is a minimal authenticated cURL call:

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What does my chart say about career timing?",
    "birthDetails": {
      "datetime": "1990-08-15T14:30:00",
      "latitude": 19.0760,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
    }
  }'

The same key works for the deterministic computation layer. The V2 endpoints under /v2/astrology/* take flat parameters (datetime, latitude, longitude, timezone) and return raw chart data rather than prose, which is what you want when you are rendering your own UI.

Adding the header from code

In any HTTP client, authentication is just one more header. The pattern is identical whether you call the AI query, the streaming variant, or a V2 computation route:

const res = await fetch("https://api.vedika.io/api/v1/astrology/query", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VEDIKA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "When is a favourable window for a new venture?",
    birthDetails: {
      datetime: "1988-03-21T09:05:00",
      latitude: 28.6139,
      longitude: 77.2090,
      timezone: "Asia/Kolkata",
    },
    speed: "fast",
  }),
});

if (res.status === 401) throw new Error("Bad or missing API key");
const data = await res.json();

The optional speed: "fast" field routes the request to the lower-latency path (available on Business and above). It does not change how you authenticate.

Python with environment-based secrets

import os
import requests

API_KEY = os.environ["VEDIKA_API_KEY"]

resp = requests.post(
    "https://api.vedika.io/api/v1/astrology/query",
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    json={
        "question": "Summarise the strengths in this natal chart.",
        "birthDetails": {
            "datetime": "1995-11-02T18:45:00",
            "latitude": 13.0827,
            "longitude": 80.2707,
            "timezone": "Asia/Kolkata",
        },
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Streaming responses keep the same auth

For chat-style experiences, POST /api/v1/astrology/query/stream returns Server-Sent Events so you can render tokens as they arrive. Authentication is unchanged: the x-api-key header travels with the initial request, and the SSE connection inherits it. You do not need a separate streaming token or a websocket upgrade credential.

curl -N -X POST https://api.vedika.io/api/v1/astrology/query/stream \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question":"Describe the current planetary period.","birthDetails":{"datetime":"1990-08-15T14:30:00","latitude":19.0760,"longitude":72.8777,"timezone":"Asia/Kolkata"}}'

Securing keys in production

A live key maps directly to billable spend, so treat it like a database password. The failure modes here are mundane and preventable.

• Keep keys server-side. Never embed a vk_live_ key in a mobile app bundle, a single-page app, or any client a user can inspect. Proxy through your own backend so the secret stays on infrastructure you control.
• Use a secret manager or env vars. Read the key from the environment at runtime. Do not commit it; add a pre-commit secret scanner so an accidental paste never reaches the remote.
• Scope by environment. Use separate keys for staging and production so you can revoke one without touching the other, and so your dashboards attribute spend correctly.
• Rotate on a schedule and on suspicion. Generate the replacement first, cut traffic over, verify, then revoke the old key. Because keys are independent, the overlap window means zero downtime.
• Watch your wallet balance. Configure low-balance alerts. A spike in spend is often the first signal that a key has leaked.

Debugging authentication errors

Most auth problems resolve in under a minute once you know what to check. Work down this list before opening a support ticket.

A practical tip: when a request fails, log the response body, not just the status code. The error payload names the specific cause without leaking anything sensitive, which turns most 401 and 403 investigations into a single read.

Test for free before you integrate

You do not need a key to learn the request and response shapes. The free sandbox serves mock endpoints that mirror the real contract, so you can wire up your client, confirm your JSON bodies, and handle the response structure with no auth and no billing. Once your integration works against the sandbox, switching to production is a one-line change: point the base URL at api.vedika.io and add your x-api-key header.

This separation is deliberate. It lets a developer evaluate the whole surface area, more than 600 operations across 25 domains spanning Vedic, Western, and KP systems, before committing a budget. When you are ready to go live, the full request shapes and per-endpoint reference live in the documentation.

Key facts

• Authentication uses the x-api-key request header on every call.
• Production keys are prefixed vk_live_; enterprise keys are vk_ent_; vk_test_ is rejected on production.
• The base URL is https://api.vedika.io; keys are header-only, never query parameters.
• One key authenticates the AI endpoints under /api/v1/astrology/ and the V2 computation endpoints under /v2/astrology/.
• The main AI endpoint is POST /api/v1/astrology/query; streaming is POST /api/v1/astrology/query/stream (SSE).
• Keys draw against a prepaid wallet, so leaked-key exposure is bounded by your balance.
• The free sandbox at vedika.io/sandbox needs no key and mirrors the production contract.
• Rotate with no downtime: create the new key, cut over, verify, then revoke the old one.

FAQ

What header does the astrology API use for authentication?

Send your key in the x-api-key request header, for example x-api-key: vk_live_YOUR_API_KEY. There is no OAuth flow or bearer-token exchange for standard requests; the key alone authenticates and identifies your account for billing and rate limiting.

Do I need an API key to try the endpoints?

No. The free sandbox at vedika.io/sandbox exposes mock endpoints that return realistic shapes without a key. You only need a vk_live_ key when you call api.vedika.io for real, billed responses.

Why am I getting a 401 Unauthorized error?

The most common causes are a missing or misspelled x-api-key header, a key with leading or trailing whitespace, a test-format key sent to production, or a revoked key. Confirm the header name, trim the value, and verify the key is active.

How do I rotate a leaked key without downtime?

Generate a new key first, deploy it, confirm traffic flows on it, then revoke the old one. Because keys are independent, both can be valid during the overlap window, so service never drops.

Is the same key valid for the AI query and the V2 computation endpoints?

Yes. One vk_live_ key authenticates both the AI endpoints under /api/v1/astrology/ and the deterministic computation endpoints under /v2/astrology/. Scope and limits follow your plan, not separate keys per endpoint family.