How to authenticate with the QWED API.
API keys
All requests require an API key.
SDK authentication
Environment variables
Set your API key as an environment variable:
Then the SDK will auto-detect it:
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
- Never commit API keys to version control
- Use environment variables in production
- Rotate keys regularly using the dashboard
- Set IP allowlists for production keys
- 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).