Authentication

oneapi.finance uses bearer-token API keys. Every request must include an Authorization: Bearer <key> header. Keys are bound to a customer account, not to a single machine, but you should still mint one key per environment.

Key format

API keys have two visible parts and one hidden part:

oa_live_abcd1234efgh5678ijkl9012mnop3456
^^^^^^^^^^^^^^^^                ^^^^^^^^
prefix                          rest of secret

• Mode prefix — oa_live_ for production keys, oa_test_ for sandbox keys that hit the same endpoints but only return cached data and never count against your monthly quota. Test-mode keys are useful for CI runs and integration tests.
• Key body — 32 random base32 characters. The first 8 characters are stored in plaintext as a lookup prefix; the rest is hashed with SHA-256 and only the hash is persisted.

Because we only store the hash, we cannot show you the secret again after creation. If you lose a key, revoke it and mint a new one.

Sending the key

Always send the key in the Authorization header:

GET /v1/quote?symbol=AAPL HTTP/1.1
Host: api.oneapi.finance
Authorization: Bearer oa_live_abcd1234efgh5678ijkl9012mnop3456
Accept: application/json

Query-string keys (?api_key=...) are not accepted. They show up in HTTP server logs, browser histories, CDN access logs, and proxy traces, and we treat that as an exfiltration risk.

Never embed live keys in browser code

An oa_live_ key has full access to your account’s quota. Never ship one in a client-side bundle or a mobile app’s Info.plist. Put your own server in front of oneapi.finance and proxy authenticated requests through it.

Key scopes

Every key carries a scopes array. The default scope is ["read"], which grants read access to every GET endpoint. Reserved scopes for future use:

Scope	Allows
read	All current GET /v1/* endpoints.
usage	GET /v1/usage even if read is absent.
admin	Reserved. Not yet used.

You can pass a comma-separated list to POST /v1/keys when creating a key programmatically.

Key rotation

We recommend rotating keys at least every 90 days, and immediately on:

• A team member with access leaves.
• A laptop or CI runner goes missing.
• A key shows up in a stack trace, log file, or screenshot.
• You see unexpected usage spikes in the dashboard.

The rotation procedure is zero-downtime:

1. Mint a new key in the dashboard.
2. Deploy the new key alongside the old one (for example, via your secret manager).
3. Switch traffic to the new key. The simplest pattern is to set a single ONEAPI_KEY environment variable to the new value and redeploy.
4. Revoke the old key in the dashboard.

Revoked keys return 401 unauthenticated immediately on the next request.

Test mode

Test-mode keys (oa_test_...) hit the same endpoints and return the same shape. They differ in three ways:

1. They never count against your monthly quota.
2. They serve from cache only and never trigger an upstream fetch. If a symbol is not already cached, you get 404 not_found.
3. They never trigger billing events.

Use test-mode keys in CI and integration tests so a flaky test cannot drain your quota or hit a paid upstream.

Security checklist

• Send keys only over HTTPS. Plain HTTP is rejected at the edge.
• Store keys in a secret manager (AWS Secrets Manager, GCP Secret Manager, Doppler, 1Password Secrets Automation, Vercel/Render env vars). Do not commit them to git.
• Use a dedicated key per environment (local, staging, production). Tag keys with a memorable name; the dashboard shows the last 4 characters and last-used timestamp.
• Pin a per-key IP allowlist if your traffic comes from a small number of static IPs. Configure in the dashboard under Keys → Restrictions.
• Monitor last_used_at. A key that goes silent for 60 days is a candidate for revocation.

What’s next

• Rate limits — quotas, GCRA, and 429 handling.
• Errors — full status code reference.