API authentication, the Bearer ak_xxx flow

Written by Aashiq, Founder, AskVault · Reviewed by Aashiq

Last updated: May 15, 2026 · 4 min read

TL;DR

Every AskVault API request needs an Authorization: Bearer ak_xxx header. Generate keys under Dashboard > API Keys. Keys are shown once at creation; only the SHA-256 hash is stored. Per-key rate limits up to 50,000 queries per day on Business. Rotate quarterly.

The header

Every request to /v1/* requires this header:

Authorization: Bearer ak_5b45ff_yourkeyhere

No Token, Key, or other prefix. The literal word Bearer, a single space, then the full key including the ak_ prefix. Missing or malformed headers return HTTP 401 Unauthorized.

Key format and lifecycle

API keys look like ak_5b45ff_RANDOM32CHARS. The middle segment (5b45ff in this example) is your workspace's short identifier; the trailing segment is 32 characters of cryptographically random data.

Lifecycle:

1. Generated under Dashboard > API Keys > Create new key. Shown to you once.
2. Stored server-side only as SHA-256 hash. The original key is never recoverable.
3. Active until you explicitly revoke it.
4. Revoked by clicking Revoke in the dashboard. Effective immediately; subsequent requests with the revoked key return 401.

Lost keys can't be recovered. Generate a new one and revoke the old one.

Per-key rate limits

Every key has independent per-minute and per-day rate limits scoped to your plan tier:

Plan	Per minute	Per day	Per key configurable
Free	10	100	No
Starter	60	3,000	Yes
Growth	200	15,000	Yes
Business	1,000	50,000	Yes
Enterprise	Custom	Custom	Yes

On Starter and above you can tighten per-key limits below the plan defaults. Useful if you have one key powering a customer-facing app and want to cap that key's usage independently of internal use.

Every response carries rate-limit headers:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 47
X-RateLimit-Limit-Day: 3000
X-RateLimit-Remaining-Day: 2845
X-RateLimit-Reset-Day: 1747353600

When you exceed the cap you get HTTP 429 Too Many Requests with Retry-After in seconds. Back off, then retry.

Generate a key

In the AskVault dashboard:

1. Dashboard > API Keys.
2. Create new key.
3. Give it a name (e.g., production-website, staging-test, mobile-app-ios).
4. Pick a per-minute and per-day rate limit if you want tighter than plan defaults.
5. Click Generate.

The key (ak_5b45ff_...) is shown once. Copy it now. Store it somewhere safe (a secrets manager, environment variable, or password manager). After you close the dialog there's no way to retrieve the original.

We recommend creating separate keys per environment (production, staging, development) and per consumer (your backend, your mobile app, your CRM integration). Tight scoping makes revocation safer if one key leaks.

Test your key

The simplest verification request:

curl

curl -X POST https://api.askvault.co/v1/query \
-H "Authorization: Bearer ak_xxx" \
-H "Content-Type: application/json" \
-d '{"workspace_id":"wt_xxx","message":"test"}'

Python

import requests
r = requests.post("https://api.askvault.co/v1/query",
  headers={"Authorization": "Bearer ak_xxx"},
  json={"workspace_id": "wt_xxx", "message": "test"})
print(r.status_code, r.json())

Node.js

const r = await fetch("https://api.askvault.co/v1/query", {
method: "POST",
headers: { "Authorization": "Bearer ak_xxx", "Content-Type": "application/json" },
body: JSON.stringify({ workspace_id: "wt_xxx", message: "test" }),
});
console.log(r.status, await r.json());

Status 200 with a JSON answer field means auth works. Status 401 means the key is wrong.

Rotation

Best practice: rotate keys every quarter, or immediately after any leak suspicion.

The rotation flow:

1. Generate a new key with the same name suffix as the old (e.g., production-website-2026q2).
2. Update your production secrets to use the new key.
3. Deploy.
4. Once you've verified the new key works in production for at least 24 hours, revoke the old key.
5. Confirm no traffic was using the old key by inspecting Dashboard > API Keys > [old key] > Last Used.

Zero-downtime rotation. The two keys both work during the overlap window.

Security recommendations

Three things matter most:

1. Never commit keys to source control. Use environment variables (ASKVAULT_API_KEY) or a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler).
2. Don't expose keys to the browser. API keys grant full workspace access. If you need browser-side calls, use the widget channel which authenticates with a public workspace token plus per-domain rate limiting, or proxy through your backend.
3. Monitor for anomalies. Under Dashboard > API Keys > [key] > Usage, watch for sudden spikes. Unexpected traffic often signals a leaked key.

Common pitfalls

401 on every request. Header is malformed. Double-check that it's Authorization: Bearer ak_xxx with the right spacing and no quotes around the value.

Worked yesterday, fails today. Key was revoked, expired due to admin action, or the workspace was deleted. Check Dashboard > API Keys > [key] > Status.

Works locally, fails in production. Different environment variables. Confirm production has the right ASKVAULT_API_KEY and that it matches a current active key.

Same key works for some endpoints but not others. No, API keys grant uniform access to all /v1/* endpoints. If some endpoints 401 and others don't, you're sending different headers per endpoint. Debug your HTTP client.

FAQ

Can a single key cover multiple workspaces?

No. Each key is bound to one workspace at creation. To call multiple workspaces, generate separate keys per workspace.

Can I use the same key from multiple machines?

Yes. Keys are not tied to specific machines or IPs. The same key can be in use from your backend, your CI, your mobile app, and your laptop simultaneously. Rate limits aggregate across all callers using that key.

Can I scope a key to read-only access?

Not yet. All keys grant the same full access to /v1/* endpoints. Read-only scoping is on the roadmap.

What happens to in-flight requests when I revoke a key?

In-flight requests complete normally. New requests after revocation return 401 immediately.

Are there OAuth or JWT options?

The Bearer-key flow is the only one for /v1/* today. OAuth is supported for Enterprise contracts; reach out to sales@askvault.co if you need it.

Related guides

• Getting started with the AskVault API
• POST /v1/query reference
• Rate limits per plan
• Error codes
• Webhooks

Start building with the AskVault API

Generate an API key in the dashboard, then send your first request.

Get an API key → Read the API docs

Was this page helpful? Yes No