Authentication and keys

Send a key or token on every request as a bearer token:

Authorization: Bearer sk_live_...

A missing header returns 401 unauthorized. So does a header that is not of the form Bearer <value>, an unknown key and a revoked key. The only operation that needs no key is GET /v1/meta; it accepts any credential or none (a secret key sent from a browser is still refused).

A HEAD request is gated and billed exactly like the GET it mirrors: the same credential checks, rate limits and credits apply, and only the body is left out. A path under /v1 that is not an operation returns 404 not_found, and a method other than GET, HEAD or POST returns 405 method_not_allowed.

Key types

Prefix	Where it runs	Credits	Limits
sk_live_	Your servers only	Drawn from your organization	The key’s rate limit (requests per minute), an optional monthly credit cap
sk_test_	Your servers only	None	10 requests per minute and 100 credits’ worth of requests per day (UTC) for the whole organization
pk_	Browsers, on the origins you allow	Drawn from your organization	Its own rate limit per visitor IP, a required monthly credit cap (default 2,000)
ct_	Mobile and browser apps, issued by your backend	Drawn from your organization	At most 15 minutes, only the scoped endpoints, the smaller of its own cap and the issuing key’s
demo	Anywhere	None	Sample subjects only, 10 requests per minute per IP

You create, name, roll and revoke keys in the dashboard. Secrets are shown once and stored only as a hash. A revoked key stops working within two minutes, because key lookups are cached briefly at the edge.

Secret keys: sk_live_ and sk_test_

Secret keys belong on servers. A request that carries a secret key and an Origin header (which every browser sends on cross-origin calls) is refused:

{
  "type": "https://navapatra.com/docs/errors#secret_key_in_browser",
  "title": "Secret key used from a browser",
  "status": 403,
  "detail": "Secret keys (sk_) are server-only. From a browser use a publishable key (pk_) with an origin allowlist, or a short-lived client token from POST /v1/tokens via your backend.",
  "code": "secret_key_in_browser",
  "requestId": "1a5823b0-da30-4d5c-bcab-8ad6ff3749f6"
}

Test keys (sk_test_) return exactly what live keys return and never use credits, which makes them right for CI and local development. They share one budget per organization: 10 requests per minute and a daily quota of 100 per UTC day. The quota counts what each request would cost a live key, so a 62-day panchang range uses 2 of it and a batch of 10 pairs uses 10. Requests to zero-credit endpoints such as /v1/places/search do not count. Test keys cannot create client tokens.

Publishable keys: pk_

A publishable key is safe to put in web page source because it only works from the origins on its allowlist. Each allowlist entry is an exact origin such as https://app.example.com (scheme, host and port). A request without an Origin header, or from any other origin, is refused with 403 origin_not_allowed.

Origin is advisory

Browsers set Origin honestly, but any non-browser client can send whatever it likes. A pk_ key therefore limits casual reuse, not determined abuse. That is why every publishable key has a monthly credit cap: 2,000 credits unless you set another value in the dashboard, and it cannot be removed. Keep its rate limit low too. When the cap is reached the key returns 402 credit_cap_reached until the next UTC month.

Use a publishable key for widgets and for web apps that call the API directly. For anything that needs a tighter grip, use client tokens.

Client tokens: ct_

A client token is a short-lived credential your backend creates with a live secret key and hands to an app. It lasts at most 15 minutes, works only for the endpoints you list, and can carry its own credit cap. It is the right choice for mobile apps: see Mobile apps for the full pattern.

POST/v1/tokens0 creditsReference

curl https://api.navapatra.com/v1/tokens \
  -H "Authorization: Bearer $NAVAPATRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["kundali", "charts.svg"], "ttlSeconds": 600, "creditCap": 20 }'

{
  "token": "ct_eyJ2IjoxLCJqdGkiOiJkOTcxYjg3NS01MGZlLTRk...",
  "expiresAt": "2026-10-10T15:57:53Z",
  "scopes": ["kundali", "charts.svg"],
  "creditCap": 20
}

Field	Rules
scopes	Required, at least one endpoint id from the list below
ttlSeconds	60 to 900. Default and maximum 900 (15 minutes)
creditCap	Optional. Most credits the token may use over its lifetime

Scope ids: kundali, kundali.planets, dasha, matching.ashtakoota, matching.ashtakoota.batch, matching.rashi, panchang.day, panchang.range, calendar.convert, calendar.month, charts.svg, places.search, timezone.

A token inherits the organization, plan and pinned API version of the key that created it. It also shares that key’s limits: its calls count toward the key’s monthly credit cap and draw from the key’s rate-limit bucket, and its effective cap is the smaller of its own creditCap and what is left of the key’s cap. Revoking the key stops every token it issued within 60 seconds.

Tokens are opaque strings; do not parse them. Tokens issued before 11 October 2026 used an older format and are refused with 401 unauthorized: ask your backend for a new one. Calling an endpoint outside its scopes returns 403 forbidden, and that includes /v1/usage and /v1/tokens; /v1/meta needs no scope. After expiry the token returns 401 token_expired: ask your backend for a new one. Only sk_live_ keys may call /v1/tokens; anything else gets 403 forbidden.

The demo key

The public key demo exists so you can try the API before signing up, from the Quickstart or the request console in the API reference. It accepts the five sample births listed by GET /v1/meta (and the same five places for panchang, month grids and time zones), allows 10 requests per minute per IP address, and never touches an account. Anything else returns 403 demo_restricted.

The demo key cannot call batch matching, panchang ranges, /v1/tokens or /v1/usage, and it cannot send a kundali payload in place of birth input.

Which key should I use?

• A backend, script or cron job: sk_test_ while you build, sk_live_ in production.
• A web page or widget: a pk_ key with your site’s origins on its allowlist and a credit cap, or a client token from your backend.
• A React Native or Flutter app: a client token from your backend. Never ship sk_ or pk_ keys in an app bundle.
• Trying things out: demo.

Check your balance

GET /v1/usage returns your organization’s balance by credit lot and this key’s usage this month. It needs a secret key (sk_live_ or sk_test_); publishable keys, client tokens and the demo key get 403 forbidden. See Credits and metering.