Generate and rotate API keys

API keys are M2M tokens (Machine-to-Machine) for programmatic access — CI scripts, custom integrations, dashboards. Create at Settings → Personal → API Keys → New API key. The full key is shown once on creation — copy and store it securely. Revoke via DELETE on the same page.

Who is this for

Admins, developers, and anyone integrating Wevion with external systems (BI tools, CI pipelines, internal dashboards). Useful but not needed for normal interactive use.

What an API key is

An API key is a long random string Wevion accepts as proof of identity for API calls:

Authorization: Bearer wv_live_abc123...xyz789

It carries the same permissions as the user who created it. There are no granular scopes (per-resource ACLs) yet — a key generated by an admin has admin power; a key generated by a viewer has viewer power.

So choose carefully which user creates which keys:

• API key for a public dashboard → create from a viewer account

• API key for a CI launch script → create from a mediabuyer account

• API key for org-wide reporting → create from an admin account

How to create a key

Step 1: Open API Keys

Navigate to Settings → Personal → API Keys (URL: /settings/personal/api-keys).

Step 2: Click New API key

The page shows your existing keys (names + last-used + expiry, not the secrets). Click New API key.

Step 3: Configure the key

A drawer opens:

• Name (required): meaningful label, e.g. "BI dashboard production", "CI launch script". Used for revocation later

• Expires at (optional): set an expiry date (recommended for time-bound integrations). Leave blank for no expiry

• Rate limit (optional, advanced): override default rate limit (100 req/min)

Click Create key. Backend calls POST /api/v1/api-keys.

Step 4: Copy the key NOW

A modal shows the full key value, only this once:

wv_live_abc123XYZ...zZ9

• Copy to your clipboard

• Paste into your secret manager (1Password, AWS Secrets Manager, GitHub Secrets, environment variable)

• Do not save in plain text, git, or shared notes

Close the modal. The key is now active. Wevion stores only the hash; the plaintext is irrecoverable.

Step 5: Use the key

In your HTTP client / SDK:

curl -H "Authorization: Bearer wv_live_abc123XYZ...zZ9" \
     https://api.wevion.ai/api/v1/billing/subscription

The key authenticates as the user who created it. Calls land in the user's session context (workspaces accessible, role enforcement, audit logging).

How to list and revoke keys

List

Settings → Personal → API Keys. The table shows:

• Name

• Prefix (first ~10 chars, for identification — full secret never shown again)

• Created date

• Expires at

• Last used (timestamp + IP)

• Rate limit (requests/min)

• Status (Active / Revoked / Expired)

• Action: Revoke

Revoke

Click Revoke on any row. Backend calls DELETE /api/v1/api-keys/:id. The key is immediately invalidated — next request with that key returns 401 Unauthorized. Cannot be undone — to restore access, create a new key.

Rate limits

Default per key: 100 requests/minute. If exceeded:

• API returns 429 Too Many Requests

• Headers include Retry-After with seconds until allowed

• Audit log records rate-limit hits

For high-throughput integrations:

• Adjust per-key rate limit on creation (within plan-allowed maximum)

• Use multiple keys for parallel workers (but careful with audit attribution)

• Enterprise: contact CSM for custom rate-limit grants

Key rotation best practices

When to rotate

Rotation procedure

1. Create the new key with a slightly different name (e.g. "BI dashboard prod 2026-Q2")

2. Update your secret manager / env var to the new key

3. Deploy / redeploy services using the secret

4. Verify the new key works (check Last used updates)

5. Then revoke the old key

6. Verify nothing breaks for 24-48 hours

Multiple keys vs sharing one

Multiple keys are better than sharing one across integrations:

• Per-integration revocation (revoke one without breaking others)

• Per-integration audit (last-used + audit log filter by key)

• Per-integration rate limit

But each key counts as 1 row in your API keys table — keep names descriptive.

What happens when a key's user is removed

If the user who created a key is removed from the workspace, the key may continue to work (depends on configuration — keys are user-bound, but removal can soft-delete the user_session).

Safest practice: revoke the user's API keys before removing them. The Remove member flow has an optional checkbox "Also revoke their API keys" (team-107).

Audit and logging

Every API key call is logged:

• Audit log (action: api_call, metadata: { key_id, endpoint, status })

• Rate-limit hits logged separately

• Last-used timestamp on the key row updates

For full audit log details see team-113.

Plan limits

API keys are unlimited on most plans. Some plan tiers may cap simultaneous active keys per user — see /settings/team/billing if you hit a creation limit.

What an API key is NOT

• Not impersonation: keys always act as the creator, never as another user

• Not for SSO: SSO is for interactive login; keys are for M2M

• Not OAuth tokens: Wevion uses OAuth (BetterAuth) for browser sessions; API keys are a separate mechanism for headless access

• Not a permanent admin elevation: a key by a viewer is still viewer-level

Common issues

• "Cannot copy key": the modal closed before you copied. Create a new key (the old can't be re-shown).

• 401 Unauthorized on first use: check the header format: Authorization: Bearer <key> (note the space and capital B). Check the key was copied without trailing whitespace.

• 429 Too Many Requests: rate limit hit. Wait per Retry-After header or increase the limit.

• Key disappeared from list: was revoked (status filter may hide revoked keys; toggle "Show revoked"). Or expired.

• Last-used shows "never" but I've used it: cache delay; should populate within a few minutes.

• Cannot delete a key I created: shouldn't happen for your own keys. For others' keys you need admin role.

Security checklist

• ✅ Name each key with the integration it's used by

• ✅ Set expiry for short-term integrations

• ✅ Rotate quarterly even without specific reason

• ✅ Store in secret manager, never in code or shared docs

• ✅ Revoke immediately on suspected compromise

• ✅ Audit log review monthly for unexpected key usage

• ✅ Revoke departed employees' keys at offboarding

Related

• Security best practices for your team — broader checklist

• Read your audit log — track key usage

• Set up two-factor authentication — secure the human side