API Keys — tnea_ & tnsr_¶

NumerologyAPI uses two families of API keys. Both look similar, are generated with the same 80-character secure format, and authenticate with the same X-API-Key header — but they are metered differently and are intended for different products.

1. Key Format & Security¶

Every key is exactly 80 characters long:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• The 4-character prefix identifies the key type; the remaining 75 characters are generated with a cryptographically secure random source.
• Keys are stored SHA-256 hashed server-side. The plaintext key is shown only once, at creation time.
• If a key is ever exposed, rotate it immediately from the dashboard.

2. Platform Keys (tnea_)¶

Platform keys are the standard keys for integrating NumerologyAPI into your own product — websites, mobile apps, and server-side services.

Authentication¶

Send the key on every request with the X-API-Key header:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Metering¶

Billable /api/v1 calls are deducted from your organization's credits wallet (pay-as-you-go). You can top up the wallet at any time from the dashboard.

Channel rule: platform keys must not send the X-Numora-Client header. Sending it returns 403 — that header is reserved for the desktop channel.

3. Numora Studio Keys (tnsr_)¶

Numora Studio keys authenticate the Numora Studio desktop app (macOS/Windows) used by practitioners to generate client reports. They are a sibling of platform keys with an identical format, but they are billed against the organization's Numora Studio plan allowance instead of platform credits.

Provisioning¶

A tnsr_ key is created either:

• through the desktop app sign-in flow (the browser consent page provisions a key automatically), or
• manually on the dashboard API Keys page (/api-keys).

Channel signature (mandatory)¶

Every call made with a tnsr_ key must include the desktop channel header:

Server enforcement:

• tnsr_ key without X-Numora-Client → 403.
• tnea_ key with X-Numora-Client → 403.

Metering¶

• Billable /api/v1 calls deduct from the organization's Numora Studio plan allowance (one shared pool across all tnsr_ keys of the organization).
• A credit fallback toggle exists per tnsr_ key: when the plan allowance is exhausted, the key may fall back to the organization's platform credits (off by default).
• If the allowance is exhausted and no fallback is enabled, calls return 429.

Device locking (optional)¶

A tnsr_ key can be locked to registered devices. With locking enabled, every request must carry an X-Numora-Device-Id registered to the organization; unregistered devices are rejected with 403.

Desktop-exclusive endpoints¶

Some endpoints are reserved for the desktop channel and return 403 for tnea_ keys:

• POST /api/v1/numora/report-bundle — full client report in one call
• POST /api/v1/numora/order — in-app plan/allowance purchase flow
• POST /api/v1/numora/devices/register — register a desktop install
• GET /api/v1/numora/studio-status — desktop balances and quota meters

Tip: billable responses also carry X-Remaining-Credits and X-Remaining-Tokens headers so you can track live balances without extra calls.

4. Managing Keys (Dashboard)¶

The dashboard API Keys page (/api-keys) is the control center for both key types.

Roles: admin and developer roles can create and manage keys. finance cannot create production API keys. Financial operations (plan purchases, top-ups) are limited to admin and finance.

Multiple keys: organizations can hold many keys of both types — for example one tnsr_ key per practitioner or per desktop install. Allowances are shared per organization, so keys never "compete" for their own balance.

5. Best Practices¶

• Treat keys like passwords. Never embed them in client-side code, public repositories, or logs.
• Use environment variables or a secrets manager in your backend.
• Rotate immediately if a key is compromised or a team member leaves.
• Use one tnsr_ key per desktop install to simplify device management and revocation.
• Enable device locking for high-security organizations.
• Monitor usage in the dashboard to catch unexpected spikes early.

6. Common Questions¶

Can a tnsr_ key call regular platform endpoints? Yes. Numora Studio keys authenticate the whole /api/v1 surface; those calls are billed against the Numora Studio plan allowance.

Can a tnea_ key call desktop-exclusive /numora/* endpoints? No. Desktop-exclusive endpoints return 403 for platform keys.

Why do I get 403 when calling with my tnsr_ key? Most likely the X-Numora-Client header is missing or the app id does not match. Check that every request includes X-Numora-Client: numora-studio/<version>.

Why do I get 403 with my tnea_ key? Platform keys must not carry the X-Numora-Client header — remove it.

What happens when my allowance runs out? Billable calls return 429 unless credit fallback is enabled on your tnsr_ key (or you top up your platform wallet for tnea_ keys).

Related¶

• Getting Started
• Pricing
• Enterprise Solutions