Authentication & API Keys
Authenticate with the ComplyWise API using email/password login, JWT tokens, and API keys for service-to-service integrations.
On this page
Authentication Overview
The ComplyWise API uses token-based authentication. All API requests (except login) must include a valid Bearer token in the Authorization header. Tokens are obtained via the login endpoint and include the user's organization, role, and expiration. For service-to-service and CI/CD integrations, API keys provide long-lived authentication.
- Bearer tokens for all authenticated requests
- Tokens include organization, user, and role information
- Tokens expire automatically
- API keys for long-lived service-to-service authentication
Login Endpoint
POST /api/auth/login — Authenticate with email and password to receive a JWT access token. The request body must include email and password as JSON. The response includes the access_token, token_type (Bearer), user profile, and tenant information. Include the token in all subsequent requests as: Authorization: Bearer {access_token}.
- Method: POST
- URL: /api/auth/login
- Body: { "email": "user@example.com", "password": "your-password" }
- Response: { "access_token": "eyJ...", "token_type": "bearer", "user": { ... } }
Using the Token
Include the access token in the Authorization header of every API request. The format is: Authorization: Bearer {access_token}. If the token is expired or invalid, the API returns a 401 Unauthorized response. Refresh your token by calling the login endpoint again.
- Header: Authorization: Bearer {access_token}
- 401 response indicates an expired or invalid token
- Refresh by calling the login endpoint again
API Keys
API keys provide persistent authentication for automated systems, scripts, and CI/CD pipelines. Create API keys from Settings → API Keys in the dashboard. Each key inherits the role and tenant of the creating user. API keys are sent in the same Authorization: Bearer header as JWT tokens.
- Create in Settings → API Keys with a descriptive name
- Keys inherit the creating user's role and tenant scope
- Configurable expiration — revoke when no longer needed
- Use separate keys for each integration for easy revocation
Rate Limiting
API requests are rate-limited per tenant to ensure fair usage and platform stability. Rate limit headers are included in every response so your integration can adapt accordingly. Enterprise customers can request higher limits.
- Standard endpoints: rate-limited per tenant
- Report generation: lower rate limit per tenant
- Rate limit headers included in all responses
- 429 Too Many Requests response when limit exceeded
Security Best Practices
Never expose your JWT token or API key in client-side code, URL parameters, or version-controlled files. Use environment variables or secret management systems for storing API keys. Rotate API keys periodically and revoke any keys that may have been compromised. Use the minimum required role when creating API keys for integrations.
- Store tokens and API keys in environment variables or secret managers
- Never commit keys to version control
- Use least-privilege roles for service API keys
- Revoke immediately if a key is suspected of compromise