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: full feature access, or questions only if the key was generated with Ask questions only. 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?

Each key has its own 60-per-minute and 1,000-per-day budget. The limits are not editable in the dashboard; support can raise a key's limits.

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 Channels > REST API.
Choose an expiry and an access level next to the button: the key never expires (default) or expires in 30 days, 90 days or 1 year; it gets Full access (default) or Ask questions only. You can't change either one in the dashboard later, so generate a new key if you need a different choice.
Click Generate Secret Key. The key is named for you (API Key 1, API Key 2 and so on). There is no naming step, so keep your own note of which key is used where.
Copy the key immediately. A banner above the list shows the full key once, with a copy button. It looks like ak_abc123.... AskVault stores only a hash, so you can't view the full key again once you dismiss the banner.

The key list has four columns: Name, Secret Key (only the start of the key, never the full value), Created and Actions. Under each name a line shows the key's access, its expiry (or Expired) and the date it was last used, for example Ask questions only · Expires Jan 1, 2027 · Never used.

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

Scopes

A key has one of two access levels, chosen when it is generated. Key creation itself is owner-only.

Full access can call every /v1/* endpoint of the workspace it was created in.
Ask questions only can call /v1/query, /v1/query/stream, /v1/agent/ask and /v1/agent/capabilities, and both workspace MCP tools. On /v1/agent/escalate, /v1/agent/csat and /v1/agent/resolve it gets HTTP 403 with {"detail": "This API key can only ask questions. Use a key with full access."}.

Ask questions only is not read-only: a question sent to /v1/agent/ask is stored as a conversation, and the AI can still hand that conversation to a person. There are no finer per-resource scopes. Use one key per integration and revoke it the moment that integration no longer needs access. Widget tokens remain the narrowly-scoped, chat-only option for anything client-side.

Expiry

A key never expires unless you pick 30 days, 90 days or 1 year when you generate it. From that date every authenticated /v1/* request and every workspace MCP call made with it returns HTTP 401 with {"detail": "API key has expired."}, and its row says Expired. Generate the next key and rotate before the date.

Per-key rate limits

Each key has its own budget, separate from your other keys:

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

The limits cannot be changed in the dashboard. Support can raise a key's limits up to 1,000 a minute and 100,000 a day. Using one key per integration keeps one busy integration from using up another's budget.

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. The key's row shows the date it was last used on any /v1/* endpoint or the workspace MCP server. There is no per-key usage count, so check your own request logs to confirm nothing still calls 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 Channels > REST API and click Revoke in the key's Actions column.
Confirm. The dialog warns that any integration using the key stops working immediately.

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 stay in the list marked Revoked and can't be reinstated. Generate a new key if needed.

Usage per key

The key list shows only the date each key was last used. There is no per-key query count or daily breakdown in the dashboard today. To see who is calling with which key, log the key you send on your own side, or watch your own request logs. Key creation and revocation events are recorded in the workspace audit trail; the activity log view of it is rolling out.

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 your own request logs. An unexpected spike in calls 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 '{
    "query": "What is your refund policy?"
  }'

The Bearer prefix is required. The key identifies the workspace, so the request needs no workspace ID. 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

Key creation and revocation are recorded in the workspace audit trail. Viewing it in the activity log is rolling out and may not be on for your account yet.

Planned features (on the roadmap)

Documented for accuracy:

Per-resource scopes. Today, a key is either full access or ask questions only. Finer per-resource scopes 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 per key; support can raise them.

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. The key's budget is too low for your traffic. Spread work across keys, or ask support to raise the limit.

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, or questions only for a key generated with Ask questions only.

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?

Each key has its own budget. Changing it is done by support, not in the dashboard.

Was this page helpful?