Can I see the full value of an AskVault API key after it's created?

No. The full key is shown only once at creation. AskVault stores a one-way hash, not the plaintext. If you lose the key, revoke it and generate a new one.

What is the difference between an AskVault API key and a widget token?

Widget tokens are client-side (embedded in browser pages), origin-restricted by domain allowlist, and scoped to chat queries only. API keys are server-side secrets with broader scope and full feature access — never expose them to a browser.

What happens to in-flight requests when I revoke an AskVault API key?

Immediately. Every request re-checks the key's active status against the database, so a revoked key starts failing with HTTP 401 on its very next request. An in-flight request that was already authenticated before revocation typically completes.

Can I configure different rate limits for each AskVault API key?

Yes. Each key has its own rate limit configuration — useful for giving a high-volume integration more headroom while keeping lower-trust keys restricted.

API keys management

Written by Joseph Russo, Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan

Last updated: June 18, 2026 · 4 min read

What API keys are for

Three use cases:

Backend integrations. Your server posts queries to /v1/query from authenticated users.
Custom UI. You build your own chat widget; AskVault handles retrieval and generation.
Automation. Scripts that sync data, manage conversations, export analytics.

Different from widget tokens (used client-side, scoped narrowly). API keys are server-side, broader scope.

Generating a key

A few clicks:

Open Dashboard > API Keys > Create.
Name the key (e.g., "Production backend", "CI scripts").
Optionally set per-minute and per-day rate limits.
Click Generate.
Copy the key immediately. It looks like ak_abc123.... AskVault stores only a hash; you can't view the full key again after the page reload.

Treat the key as a password: never commit to git, never expose client-side, never log.

Scopes

API keys don't carry granular per-resource scopes today — a key gets full programmatic access to the workspace it was created in (the same access its creator has), and key creation itself is owner-only. Use one key per integration and revoke it the moment that integration no longer needs access, since there's no way to narrow an individual key's permissions after the fact. Widget tokens remain the narrowly-scoped, chat-only option for anything client-side.

Per-key rate limits

Each key can have its own rate cap separate from the workspace cap:

Requests per minute. Default 60.
Requests per day. Default 1,000.

Useful for limiting blast radius if a key leaks. Set tight defaults; raise per key as needed.

Rate limits return HTTP 429. See rate limits for details.

Rotating a key

There's no built-in "rotate with grace period" flow today — rotating a key means generating a new one and retiring the old one:

Generate a new key (see above). Both keys work at the same time.
Update your application to use the new key.
Once traffic has moved over, revoke the old key.

Because there's no automatic grace-period expiry, you control exactly when the old key stops working — just don't forget the last step.

Revoking a key

Immediate kill switch:

Open API Keys > [key] > Revoke.
Confirm.

Every request re-checks the key's active status against the database, so revocation takes effect on the very next request — no propagation delay. Use when:

Key leaked publicly.
Employee with key access left.
Suspicious activity detected.

Revoked keys can't be reinstated. Generate a new key if needed.

Usage stats per key

Each key has its own usage view:

Total queries and tokens for the selected window.
Average response time.
Last used at.
Daily breakdown of queries and tokens.

Visible under API Keys > [key] > Usage. Key creation and revocation events are also written to the workspace's audit log.

Best practices

Patterns we recommend:

One key per integration. Don't share keys between services — it's easier to tell who's using what, and to revoke just one integration's access.
Set a tight rate limit and raise it only if a legitimate integration needs more headroom.
Rotate periodically (generate new, cut over, revoke old) or immediately on suspected compromise.
Watch the usage stats. An unexpected spike in queries is the first sign of a leaked key.

Sample request

Using a key:

curl https://api.askvault.co/v1/query \
  -H "Authorization: Bearer ak_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_xxx",
    "query": "What is your refund policy?"
  }'

The Bearer prefix is required. See authentication.

Workspace-scoped, not account-scoped

Every key is tied to the workspace it was created in — a key for workspace ws_a can't access data in ws_b. There's no account-wide key today: if you operate multiple workspaces, generate a key per workspace and loop over them in your code.

Webhook signatures

When AskVault calls your webhook endpoints, requests carry a signature header:

X-AskVault-Signature: t=1715789432,v1=abc123...

Verify using the webhook secret. Different from API keys; webhook secrets sign outgoing requests, API keys authenticate incoming requests.

See webhooks reference for signature verification.

Plan availability

Free. No API access.
Starter and above. API access, up to 10 active keys per workspace. Starter+

Audit and compliance

API key usage feeds SOC 2 evidence:

Key creation events logged.
Revocation events logged.
All accessible per workspace audit log.

Useful for proving access control to auditors.

Planned features (on the roadmap)

Documented for accuracy:

Short-lived keys. Today, keys are long-lived until revoked. Time-bounded keys (e.g., 24-hour) planned.
Per-resource scopes. Today, a key gets full access to its workspace. Granular scopes (read-only, per-resource) planned.
IP allowlisting. Not available today. Planned for keys used by known-IP backends.
Cross-workspace federation. Today, per-workspace keys. Federation across workspaces planned.

Limits

Max keys per workspace. 10 active keys, on any plan with API access (Starter and above).
Default rate limits. 60 requests/minute, 1,000 requests/day — adjustable per key.
Audit retention. 365 days standard.

Common pitfalls

Key in git history. Treat as compromised. Revoke immediately, generate new, scrub git history if private.

Key in client-side code. Same as above. API keys are server-side only. Use widget tokens client-side.

Rate-limit errors at unexpected times. Per-key cap too low for your traffic. Bump under Edit Key.

Lost the key value. AskVault stores only a hash; can't show again. Generate a new key.

FAQ

Can I see the full key value after creation?

No. Only at creation time. AskVault stores a one-way hash, not the plaintext.

Widget tokens are client-side (browser), origin-restricted, narrow scope (chat queries only). API keys are server-side, broader scope, full feature access.

Technically yes, but worst-practice. Generate per-person or per-service keys to keep audit clean.

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

New requests fail with HTTP 401 immediately — every request re-checks the key's active status against the database. An in-flight request already authenticated before revocation typically completes.

Can I have multiple keys with different rate limits?

Yes. Each key has its own rate config.

Was this page helpful?