Skip to content
AskVault Docs
Try Free →

API keys management

Written by , Founder, AskVault · Reviewed by Aashiq
Last updated: · 4 min read

What API keys are for

Three use cases:

  1. Backend integrations. Your server posts queries to /v1/query from authenticated users.
  2. Custom UI. You build your own chat widget; AskVault handles retrieval and generation.
  3. 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

Five clicks:

  1. Open Dashboard > API Keys > Create.
  2. Name the key (e.g., "Production backend", "CI scripts").
  3. Pick scopes (see below).
  4. Optionally set rate limits and IP allowlist.
  5. Click Generate.
  6. Copy the key immediately. It looks like ak_live_abc123...50chars. 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

Each key carries a list of permissions:

  • read:knowledge. Read indexed content.
  • write:knowledge. Upload, edit, delete knowledge sources.
  • read:conversations. Read chat history and audit logs.
  • write:conversations. Create, update, resolve conversations.
  • read:contacts. Read contact profiles.
  • write:contacts. Create, update, delete contacts.
  • read:analytics. Read aggregated stats.
  • write:webhooks. Manage webhook subscriptions.
  • admin. Full workspace access. Use sparingly.

Principle of least privilege: grant only what the key needs. A read-only analytics script gets read:analytics, not admin.

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 10,000.
  • Burst capacity. Default 100.

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

Rate limits return HTTP 429 with Retry-After header. See rate limits for details.

IP allowlist

Restrict where the key can call from:

  1. Edit the key.
  2. Add allowed CIDR ranges (e.g., 203.0.113.0/24).
  3. Save.

Requests from non-allowlisted IPs return HTTP 403. Useful for keys used by known-IP backends (your AWS VPC, your on-prem servers).

For dynamic-IP environments (mobile apps, browser), leave the allowlist empty.

Rotating a key

Recommended every 90 to 180 days, or immediately if compromise is suspected.

  1. Open API Keys > [key] > Rotate.
  2. AskVault generates a new key AND keeps the old one active for a 24-hour grace period.
  3. Copy the new key. Update your application.
  4. After updating, click "Retire old key now" or wait for auto-retire after 24 hours.

The grace period prevents downtime during rotation. Don't skip it on production.

Revoking a key

Immediate kill switch:

  1. Open API Keys > [key] > Revoke.
  2. Confirm.
  3. Key invalid within 30 seconds globally.

All in-flight requests with the key fail immediately. 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.

Audit log per key

Each key has its own audit trail:

  • Created at, by whom.
  • Last used at.
  • Rotations and revocations.
  • Request count in the last 24 hours, 7 days, 30 days.
  • Top endpoints called.
  • Failed-auth attempts (which indicate someone trying with wrong scopes or rate-limited).

Visible under API Keys > [key] > Audit. Retained 365 days standard, 6 years Enterprise.

Best practices

Five patterns we recommend:

  1. One key per integration. Don't share keys between services. Rotation is easier when you know exactly who uses which key.
  2. Use the least scope. Read-only when possible.
  3. Rotate every 90 to 180 days. Calendar reminders work.
  4. IP allowlist whenever possible. Limits blast radius.
  5. Monitor the audit log. Unusual patterns (sudden spike, unexpected endpoint) flag for investigation.

Sample request

Using a key:

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

The Bearer prefix is required. See authentication.

Key prefixes

Two prefixes:

  • ak_live_. Production-tier key. Full features.
  • ak_test_. Test-mode key. Sandbox workspace; no quota impact; mock data.

Test keys are useful for CI/CD pipelines that shouldn't consume production quota.

Workspace-scoped vs account-scoped

Keys are workspace-scoped by default:

  • A key for workspace ws_a can't access data in ws_b.
  • A key with admin scope can manage that one workspace's settings.

For cross-workspace operations:

  • Generate per-workspace keys and loop in your code.
  • Or use an account-scoped key (Enterprise only) with read:workspaces scope to list and access all workspaces under your account.

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. Up to 2 API keys, basic scopes. Starter+
  • Growth. Up to 10 API keys, all scopes. Growth+
  • Business. Up to 50 API keys, IP allowlist, advanced rate limits. Business+
  • Enterprise. Unlimited keys, account-scoped keys, custom rate limits.

Audit and compliance

API key usage feeds SOC 2 evidence:

  • Key creation events logged.
  • Failed-auth attempts logged.
  • Rotation and 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-endpoint scopes. Today, scopes cover resource types (knowledge, conversations). Granular per-endpoint scopes planned.
  • Service account model. Today, keys are anonymous service principals. Named service accounts planned for Enterprise.
  • Cross-workspace federation. Today, per-workspace keys. Federation across workspaces planned.

Limits

  • Max keys per workspace. Plan-dependent (2 to 50 plus unlimited Enterprise).
  • Key string length. 50 characters.
  • IP allowlist entries per key. Up to 50.
  • 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.

Key works locally but not in production. IP allowlist blocks production servers. Update allowlist.

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.

What's the difference between a widget token and an API key?

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

Can I share a key across team members?

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?

They fail with HTTP 401 within 30 seconds.

Can I have multiple keys with different rate limits?

Yes. Each key has its own rate config.

Was this page helpful?