Skip to main content
WAVIS authenticates every request with a Bearer token. This page is the endpoint reference; for concepts and best practices, see Authentication.

​
Header format

Authorization: Bearer wvs_<env>_<32-hex>
Both Bearer wvs_... and bare wvs_... are accepted.
PrefixEnvironmentNotes
wvs_live_*ProductionReal billing
wvs_test_*SandboxNo Stripe billing — safe for CI
wvs_dev_*DevelopmentInternal use
wvs_trial_*Trial30-min TTL, 10-op limit

​
POST /api/v1/onboarding/temp-key

Issue a 30-minute trial key. No authentication required, IP rate-limited to 5 keys/minute.

​
Request

POST /api/v1/onboarding/temp-key
No body required.

​
Response — 200 OK

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

​
Response — 429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "IP has issued 5 trial keys in the last 60 seconds. Try again later."
  }
}

​
DELETE /api/v1/onboarding/temp-key/{key_prefix}

Revoke a trial key immediately. No auth required.

​
Request

DELETE /api/v1/onboarding/temp-key/wvs_trial_abc123
key_prefix is the first 16+ characters of the trial key (the suffix is the secret part).

​
Response — 200 OK

{
  "revoked": true,
  "message": "Trial key revoked."
}

​
POST /api/v1/keys/apikey/rotate

Rotate the calling API key. Returns a new key; the old key remains valid for 24 hours grace.

​
Request

POST /api/v1/keys/apikey/rotate
Authorization: Bearer wvs_live_<old-key>
No body.

​
Response — 200 OK

{
  "new_api_key": "wvs_live_xyz789abc012...",
  "old_key_prefix": "wvs_live_oldkey...",
  "grace_period_ends_at": "2026-04-29T12:00:00Z",
  "environment": "live"
}
The new key is shown once only. Store it before processing the response. A key_rotated webhook event fires when rotation completes.

​
GET /api/v1/user/api-keys

List API keys for the authenticated user. Requires Clerk JWT (dashboard session token), not a WAVIS API key.

​
Request

GET /api/v1/user/api-keys
Authorization: Bearer <clerk-jwt>

​
Response — 200 OK

{
  "items": [
    {
      "id": "key_abc123",
      "prefix": "wvs_live_a1b2c3",
      "created_at": "2026-04-01T10:00:00Z",
      "last_used_at": "2026-04-28T11:55:00Z",
      "environment": "live"
    }
  ],
  "total_count": 1
}

​
POST /api/v1/user/api-keys

Create a new API key. Requires Clerk JWT.

​
Request

POST /api/v1/user/api-keys
Authorization: Bearer <clerk-jwt>
Content-Type: application/json

{
  "environment": "live",
  "role": "developer"
}
FieldTypeRequiredDefaultNotes
environmentstringYes—"live", "test", or "dev"
rolestringNo"developer""viewer", "developer", "account_admin"

​
Response — 201 Created

{
  "key": "wvs_live_xyz789...",
  "id": "key_def456",
  "prefix": "wvs_live_xyz789",
  "created_at": "2026-04-28T12:00:00Z",
  "environment": "live"
}
The key field is shown once only. Rate-limited to 10 creations per user per hour.

​
DELETE /api/v1/user/api-keys/{key_id}

Revoke an API key. Requires Clerk JWT. Revocation is immediate.

​
Request

DELETE /api/v1/user/api-keys/key_abc123
Authorization: Bearer <clerk-jwt>

​
Response — 204 No Content

No body.

​
POST /api/v1/user/logout

Signal logout intent — invalidates session-bound caches. Requires Clerk JWT.

​
Request

POST /api/v1/user/logout
Authorization: Bearer <clerk-jwt>

​
Response — 200 OK

{ "status": "logged_out" }

​
RBAC roles

RoleCapabilities
viewerRead keys/usage/status only (GET)
developerManage keys/webhooks, run compute (default)
account_adminEverything developer can + billing/invoices/subscription
trialLimited to 10 ops total (assigned to wvs_trial_* keys)
Endpoints document their required role. Insufficient role → 403 Forbidden.

​
Error codes

CodeStatusCause
MISSING_AUTH_HEADER401No Authorization header
INVALID_API_KEY401Key revoked, expired, or malformed
INSUFFICIENT_ROLE403Role doesn’t permit this endpoint
BRUTE_FORCE_LOCKOUT429Too many invalid attempts; wait 15 min
IP_RATE_LIMITED429Too many trial keys from this IP
TRIAL_OPS_EXHAUSTED402Trial key has used its 10 operations

​
Brute-force protection

Two automatic lockouts protect the system:
TriggerLockout
10 invalid attempts on the same key in 5 min15-min lockout for that key
20 invalid attempts from the same IP in 5 min15-min lockout for that IP
Lockouts are returned as 429 Too Many Requests with Retry-After header. Wait or use a different IP.

​
Next Steps

Keys API

FHE key (not API key) management

Billing

Subscription and budget management