API Keys

API keys authenticate programmatic requests to the VeriWorkly API. Session cookies are designed for browser use; API keys let you integrate VeriWorkly into your own scripts and applications.

Getting an API Key

Key management lives on its own page in Studio, not inside the settings panels (the Settings page links to it).

1. Log in to app.veriworkly.com.
2. Go to /api-keys — reachable from Settings → Developer API keys, or directly.
3. Click Create key.
4. Give the key a descriptive name, pick its scopes, and optionally set a rate limit and expiry.
5. Copy the key immediately. The full value is shown exactly once and is never recoverable.

Keys are prefixed vw_ followed by 64 hex characters.

Key safety model

VeriWorkly never stores the key itself. Only an irreversible HMAC-SHA256 hash is persisted, using a hashing secret (API_KEY_HASH_SECRET) that production configuration requires to be distinct from the general auth secret. The stored record also keeps the key's first and last 8 characters; the list endpoint returns only the leading keyPrefix, which is enough to tell keys apart without being able to reconstruct one.

Each key carries:

Using your API Key

Send the key in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://api.veriworkly.com/api/v1/users/me

An Authorization bearer token is accepted as an equivalent alternative, which is often easier with HTTP clients that assume standard auth headers:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.veriworkly.com/api/v1/users/me

Scopes

A key may only carry scopes the backend recognises. Requesting an unknown scope fails the create or rotate call with 400 Unsupported API key scope(s).

Rate limits

A key's rate limit is set at creation and can be raised on rotation, up to the server-side maximum. A requested value above the maximum is clamped down to it rather than rejected.

Exceeding the limit returns 429 Too Many Requests with headers indicating when to retry:

• Retry-After — seconds to wait before the next request.
• X-RateLimit-Limit — maximum requests allowed in the window.
• X-RateLimit-Remaining — remaining requests in the current window.
• X-RateLimit-Reset — Unix timestamp when the limit resets.

Per-key limits sit on top of the general per-route IP rate limiter, so a burst can be throttled by either.

Rotation and revocation

• Rotate — issues a replacement key and retires the old one. Use this when the integration is still needed.
• Revoke — turns the key off permanently. Use this when the key should stop existing.

Authentication results are cached in Redis for 5 minutes by default (API_KEY_AUTH_CACHE_TTL_SECONDS), and that cache entry is dropped immediately when a key is revoked, so a revoked key stops working right away rather than at the end of its cache window.

The lastUsed timestamp is written at a throttled interval (API_KEY_LAST_USED_TOUCH_INTERVAL_SECONDS, default 300 seconds) rather than on every request, so it is approximate by design.

Security best practices

• Never share a key, and never commit one to version control — use environment variables.
• Prefer the smallest scope set that makes the integration work.
• Use shorter expiries for risky or short-lived integrations.
• Revoke compromised keys immediately and issue a replacement.
• Use descriptive names so an unfamiliar key is easy to trace back to its integration.

For production operating procedure — rotation schedules, incident response, release checks — see the API Key Security Runbook.