Authentication

WAVIS authenticates every API request with a Bearer token in the Authorization header. Keys are scoped to one of four environments and one of four roles.

Quick start — get a trial key

No signup, no credit card:

curl -X POST https://api.wavis.xyz/api/v1/onboarding/temp-key

{
  "api_key": "wvs_trial_abc123...",
  "expires_at": "2026-04-28T13:30:00Z",
  "ops_limit": 10,
  "message": "Trial key issued. Valid for 30 minutes, 10 operations."
}

Use it like any other API key:

curl https://api.wavis.xyz/api/v1/health \
  -H "Authorization: Bearer wvs_trial_abc123..."

Trial limits: 30-minute TTL · 10 operations · IP rate-limited to 5 keys/minute.

API key format

Every WAVIS key has the prefix wvs_<env>_<32-hex>:

Prefix	Environment	Use case
`wvs_live_*`	Production	Real billing, real workloads
`wvs_test_*`	Sandbox	No Stripe billing — safe for CI
`wvs_dev_*`	Development	Internal use only
`wvs_trial_*`	Trial	Temp keys from `/onboarding/temp-key`

The 32-hex suffix is generated from a CSPRNG. Keys are stored only as HMAC hashes server-side — we cannot recover a lost key. If you lose one, rotate it.

Sending the API key

Both forms are accepted:

Authorization: Bearer wvs_live_abc123...

Authorization: wvs_live_abc123...

Bearer-prefixed is the convention; both work.

Roles (RBAC)

Every key has a role determining which endpoints it can call:

Role	Can do	Cannot do
VIEWER	`GET` keys/usage/status	Create/modify anything
DEVELOPER	All compute, manage keys + webhooks	Billing, subscription
ACCOUNT_ADMIN	Everything DEVELOPER can + billing/invoices	—
TRIAL	Limited compute (10 ops total)	Billing, webhooks, key management

The dashboard creates DEVELOPER keys by default. Generate VIEWER keys for read-only monitoring (CI, dashboards, alerting integrations).

Creating production keys

Go to API Keys → Create new key
Pick environment (live / test / dev)
Pick role (VIEWER / DEVELOPER / ACCOUNT_ADMIN)
Copy the returned key — shown once only

Or via API (requires Clerk JWT from dashboard session):

curl -X POST https://api.wavis.xyz/api/v1/user/api-keys \
  -H "Authorization: Bearer <CLERK_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"environment": "live", "role": "developer"}'

{
  "key": "wvs_live_xyz789...",
  "id": "key_abc",
  "prefix": "wvs_live_xyz789",
  "created_at": "2026-04-28T12:00:00Z",
  "environment": "live"
}

Rate limit: 10 keys created per user per hour.

Rotating a key

curl -X POST https://api.wavis.xyz/api/v1/keys/apikey/rotate \
  -H "Authorization: Bearer <CURRENT_KEY>"

{
  "new_api_key": "wvs_live_newkey...",
  "old_key_prefix": "wvs_live_oldke...",
  "grace_period_ends_at": "2026-04-29T12:00:00Z",
  "environment": "live"
}

Rotation behavior:

The new key is returned once — store it immediately.
The old key remains valid for 24 hours as a grace period.
After 24 hours, the old key is auto-revoked.
A key_rotated webhook event fires when rotation completes.

Revoking a key

curl -X DELETE https://api.wavis.xyz/api/v1/user/api-keys/{key_id} \
  -H "Authorization: Bearer <CLERK_JWT>"

Returns 204 No Content. Revocation is immediate — no grace period.

Environment variables

Standard convention across the SDKs:

export WAVIS_API_KEY="wvs_live_..."
export WAVIS_BASE_URL="https://api.wavis.xyz"  # optional

Both SDKs auto-load WAVIS_API_KEY if you don’t pass apiKey explicitly.

Brute-force protection

WAVIS enforces two automatic lockouts:

Per-key: 10 invalid attempts in 5 minutes → 15-minute lockout for that key.
Per-IP: 20 invalid attempts in 5 minutes → 15-minute lockout for that IP.

Lockouts return 429 Too Many Requests. Wait or use a different IP.

Security best practices

Never commit keys to git. Use .env files + .gitignore, or your CI’s secret manager.
Use wvs_test_* keys in CI. They don’t trigger billing and have separate quotas.
Rotate keys quarterly. Set a calendar reminder. Use webhooks to update downstream systems automatically.
Use VIEWER role for read-only services (monitoring, dashboards). Limits blast radius if leaked.
Set a budget cap in the dashboard — even a leaked key cannot drain your account beyond the cap.

Troubleshooting

`401 Unauthorized — invalid API key`

The key was revoked, expired (trial), or the prefix was typo’d. Check dashboard.wavis.xyz → API Keys.

`403 Forbidden — insufficient role`

You’re calling a billing/admin endpoint with a DEVELOPER or VIEWER key. Generate an account_admin role key for billing operations.

`429 Too Many Requests — brute force lockout`

Too many invalid auth attempts. Wait 15 minutes, or contact support (support@wavis.xyz) if the lockout is in error.

Trial key returned `402 Payment Required`

Trial keys are limited to 10 operations. Either get a new trial key or sign up at wavis.xyz.

Getting Started

Core Concepts

SDKs

Quick start — get a trial key

API key format

Sending the API key

Roles (RBAC)

Creating production keys

Rotating a key

Revoking a key

Environment variables

Brute-force protection

Security best practices

Troubleshooting

`401 Unauthorized — invalid API key`

`403 Forbidden — insufficient role`

`429 Too Many Requests — brute force lockout`

Trial key returned `402 Payment Required`

Next Steps

API Reference

Key Management

Getting Started

Core Concepts

SDKs

​Quick start — get a trial key

​API key format

​Sending the API key

​Roles (RBAC)

​Creating production keys

​Rotating a key

​Revoking a key

​Environment variables

​Brute-force protection

​Security best practices

​Troubleshooting

​401 Unauthorized — invalid API key

​403 Forbidden — insufficient role

​429 Too Many Requests — brute force lockout

​Trial key returned 402 Payment Required

​Next Steps

API Reference

Key Management

Quick start — get a trial key

API key format

Sending the API key

Roles (RBAC)

Creating production keys

Rotating a key

Revoking a key

Environment variables

Brute-force protection

Security best practices

Troubleshooting

`401 Unauthorized — invalid API key`

`403 Forbidden — insufficient role`

`429 Too Many Requests — brute force lockout`

Trial key returned `402 Payment Required`

Next Steps