Skip to main content
How to authenticate with the QWED API.

API keys

All requests require an API key.

Header authentication

SDK authentication

Environment variables

Set your API key as an environment variable:
Then the SDK will auto-detect it:

API key format

API key storage and migration (v7.2)

As of v7.2, QWED stores API keys as HMAC-SHA256 lookup digests keyed by a dedicated server-side secret (QWED_API_KEY_LOOKUP_SECRET). Earlier versions used PBKDF2, which added ~67ms of CPU cost to every request on the unauthenticated lookup path. Because API keys are high-entropy random tokens, the key-derivation cost bought no additional brute-force resistance, so it was removed.
Breaking change. There is no legacy fallback: API keys issued before v7.2 no longer authenticate and return 401 Unauthorized. Each key must be re-issued once. The old raw key is never required:
  • Portal or API: sign in with your email and password to get a JWT, then call POST /auth/api-keys to mint a new key. This path needs no API key.
  • Rotation by key ID: call /admin/keys/rotate with the key’s ID, authenticated with any already-working key.

Self-hosted configuration

Self-hosted deployments must set QWED_API_KEY_LOOKUP_SECRET before starting the server:
  • The server fails closed at startup if the variable is missing.
  • The value must differ from QWED_JWT_SECRET_KEY. Equal values are rejected at startup, because reusing the JWT secret would break every API-key lookup on the next JWT-secret rotation.
  • Set the secret before issuing any v7.2 keys. Digests are derived from the secret active at issue time, so changing it later requires a one-time re-issue of all keys.

Security best practices

  1. Never commit API keys to version control
  2. Use environment variables in production
  3. Rotate keys regularly using the dashboard
  4. Set IP allowlists for production keys
  5. Use test keys for development

Agent authentication

Agent tokens are separate from API keys and are used for agent-specific endpoints.
Agent tokens are passed via the X-Agent-Token header:

Scopes

API keys can have restricted scopes:

Auth endpoints

The following endpoints manage user accounts and API keys via JWT-based authentication. Anonymous /auth/* routes are rate limited per client IP (default 10 requests per minute). Exceeding the limit returns 429 Too Many Requests with a Retry-After header. See Per-IP limits on authentication endpoints.

POST /auth/signup

Create a new user and organization. Returns a JWT token for immediate use. Request:
Response:

POST /auth/signin

Sign in an existing user. Request:
Response: Same format as /auth/signup.

GET /auth/me

Get the current authenticated user’s information. Requires a Bearer token in the Authorization header.

POST /auth/api-keys

Generate a new API key for the current user’s organization. Requires JWT authentication. Request:
Response:
The key field is only returned once at creation time. Store it securely.

GET /auth/api-keys

List all active API keys for the current user’s organization.

DELETE /auth/api-keys/

Revoke an API key. Performs a soft delete.

Audit endpoints

These endpoints require JWT authentication (Bearer token) and return data scoped to the authenticated user’s organization.

GET /audit/logs

Get audit logs for the current organization.

GET /audit/logs/

Get detailed information for a single audit log entry.

GET /audit/export

Export audit logs as a CSV file (up to 1,000 records).