Authentication
KoeIQ supports two authentication methods: JWT bearer tokens for browser/user sessions and X-API-Key headers for server-to-server integrations.
1. JWT Bearer Token (Browser / User Sessions)
All dashboard access and browser-initiated API calls use short-lived JWT access tokens paired with longer-lived refresh tokens.
Login
POST /api/auth/login
Content-Type: application/json
{
"email": "admin@example.com",
"password": "your_password"
}
// Response
{
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"token_type": "bearer"
}Note: If MFA is enabled, login is two-step. The first response contains
mfa_required: true and you must submit the TOTP code to POST /api/auth/mfa/verify before receiving tokens.Using the Token
GET /api/voicelogs Authorization: Bearer eyJ...
Refreshing Tokens
Access tokens expire after a short window. Use the refresh token to obtain a new access token without re-authenticating.
POST /api/auth/refresh
Content-Type: application/json
{
"refresh_token": "eyJ..."
}
// Response
{
"access_token": "eyJ...",
"token_type": "bearer"
}2. X-API-Key (Server-to-Server)
For external systems pushing audio files via the Ingest API, use an API key — no JWT required.
Generating an API Key
- Go to Settings → API Key
- Click Generate API Key
- Copy and store the key securely — it cannot be shown again
Using the API Key
POST /api/ingest/upload X-API-Key: koeiq_live_xxxxxxxxxxxx Content-Type: multipart/form-data
Warning: API keys only work on Ingest API endpoints (
/api/ingest/*). For all other endpoints, use JWT bearer tokens.3. MFA (Multi-Factor Authentication)
KoeIQ supports TOTP-based 2FA compatible with Google Authenticator, Authy, and any standard TOTP app.
| Endpoint | Purpose |
|---|---|
| POST /api/auth/mfa/setup | Begin TOTP setup — returns QR code URI |
| POST /api/auth/mfa/verify-setup | Confirm enrolment with first TOTP code |
| POST /api/auth/mfa/verify | Verify TOTP code during login flow |
| POST /api/auth/mfa/disable | Remove MFA from account |