Create API keys at Settings → Team → API Keys. Key shown once on creation. Authenticate with the x-api-key header. Grants only selected permissions.

Generate and rotate API keys

API keys are M2M tokens (Machine-to-Machine) for programmatic access — CI scripts, custom integrations, dashboards. They live under Settings → Team → API Keys and are created by super_admin, admin, or owner roles. The full key is shown once on creation — copy and store it securely. Revoke via DELETE on the same page.

Who is this for

Team owners and admins (super_admin, admin, owner) who integrate 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:

x-api-key: <your_api_key>

It carries the granular permissions selected at creation time and is bound to the selected team context. A key cannot access backoffice/admin-only APIs and should be granted only the domains/actions required by the integration.

So choose carefully which user creates which keys:

• API key for a public dashboard → grant read-only analytics/reporting permissions
• API key for a CI launch script → grant only the campaign actions it needs
• API key for org-wide reporting → create separate keys per team/context when possible

How to create a key

Step 1: Open API Keys

Navigate to Settings → Team → API Keys (URL: /settings/team/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 dialog opens:

• Name (required): meaningful label, e.g. "BI dashboard production", "CI launch script". Used for revocation later
• Permissions (required): grant only the domains/actions the integration needs (at least one permission is required)
• Expiry in days (optional): set how many days until the key expires (recommended for time-bound integrations). Leave blank for no expiry

There is no per-key rate-limit override at creation — the rate limit is applied server-side. 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:

<your_api_key_shown_once>

• 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 "x-api-key: <your_api_key>" \     https://api.wevion.ai/api/v1/billing/subscription

The key authenticates as the user who created it, with the key's own permission set and team context. Calls are audited and rate-limited per key.

How to list and revoke keys

List

Settings → Team → API Keys. The table shows:

• Name
• Prefix (first few chars, for identification — full secret never shown again)
• Created date
• Expires at
• Last used
• 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

API keys are rate-limited server-side by BetterAuth's per-key limiter. If you exceed the limit:

• API returns 429 Too Many Requests
• Headers include Retry-After with seconds until allowed

There is no per-key override at creation time. For high-throughput integrations, use multiple keys for parallel workers (mind the audit attribution), and for Enterprise contact your CSM.

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, keys are user-bound, so removal can affect keys they created.

Safest practice: revoke the user's API keys manually before removing them. The Remove member flow does not have an "also revoke their API keys" checkbox, so handle key revocation separately (team-107).

Audit and logging

API key usage is tracked:

• The key's last-used timestamp updates on each call
• BetterAuth verifies the key (hash, expiry, rate limit, last-used) on every request

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: x-api-key: <key> (not Authorization: Bearer). 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

FAQ

How do I create an API key in Wevion?

Go to Settings → Team → API Keys → New API key, give it a meaningful name, grant the permissions it needs, optionally set an expiry in days, then click Create key. Wevion shows the full key value only once — copy it immediately into a secret manager. Only the hash is stored, so the plaintext is irrecoverable.

How often should I rotate API keys?

Wevion recommends rotating keys quarterly even without a specific reason, and immediately on suspected compromise or when an employee leaves. To rotate: create a new key, update your secret manager, deploy, verify Last used updates, then revoke the old key and confirm nothing breaks over 24-48 hours.

How is a Wevion API key rate-limited?

API keys are rate-limited server-side by BetterAuth's per-key limiter. If you exceed it, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until allowed. There is no per-key override at creation time; for high-throughput needs use multiple keys or contact your CSM (Enterprise).

What happens to API keys when the user who created them is removed?

Keys are user-bound, so removing the user can affect keys they created. Wevion's safest practice is to revoke a user's keys manually before offboarding — the Remove member flow does not include an "also revoke their API keys" checkbox, so revoke keys separately (see team-107).

Related articles

• Security best practices for your team
• Read your audit log
• Set up two-factor authentication (2FA)