Authentication API

Overview

SlimRMM uses JWT (JSON Web Tokens) for user authentication and mTLS for agent authentication.

User Authentication

Login

Authenticate a user and receive access tokens.

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

Error Responses:

• 401 - Invalid credentials
• 423 - Account locked (too many attempts)

Login with MFA

If MFA is enabled, the initial login returns a partial token:

{
  "mfa_required": true,
  "mfa_type": "totp",
  "temp_token": "temp_xxx..."
}

Complete with TOTP code:

POST /api/v1/auth/login/mfa
Content-Type: application/json

{
  "temp_token": "temp_xxx...",
  "code": "123456"
}

Refresh Token

Obtain a new access token using a refresh token.

POST /api/v1/auth/refresh
Authorization: Bearer YOUR_REFRESH_TOKEN

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 900
}

Logout

Revoke current tokens.

POST /api/v1/auth/logout
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "message": "Successfully logged out"
}

Forgot Password

Request a password reset email.

POST /api/v1/auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}

Response:

{
  "message": "If the email exists, a reset link has been sent"
}

Reset Password

Complete password reset with token from email.

POST /api/v1/auth/reset-password
Content-Type: application/json

{
  "token": "reset_token_from_email",
  "new_password": "new_secure_password"
}

Token Format

Access Token

JWT payload:

{
  "sub": "user_uuid",
  "username": "admin",
  "roles": ["admin"],
  "exp": 1704067200,
  "iat": 1704066300,
  "type": "access"
}

Refresh Token

JWT payload:

{
  "sub": "user_uuid",
  "exp": 1704672000,
  "iat": 1704066300,
  "type": "refresh"
}

Token Lifetimes

Token Type	Default Lifetime	Configurable
Access Token	15 minutes	ACCESS_TOKEN_EXPIRE_MINUTES
Refresh Token	7 days	REFRESH_TOKEN_EXPIRE_DAYS

Using Tokens

Include the access token in the Authorization header:

GET /api/v1/agents/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

MFA Endpoints

Setup TOTP

Initialize TOTP MFA setup.

POST /api/v1/mfa/totp/setup
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,...",
  "backup_codes": ["12345678", "87654321", ...]
}

Verify TOTP Setup

Confirm TOTP is working.

POST /api/v1/mfa/totp/verify-setup
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "code": "123456"
}

Setup WebAuthn

Initialize WebAuthn registration.

POST /api/v1/mfa/webauthn/register/start
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "options": {
    "challenge": "...",
    "rp": { "name": "SlimRMM", "id": "rmm.example.com" },
    "user": { ... },
    "pubKeyCredParams": [ ... ]
  }
}

Complete WebAuthn Registration

POST /api/v1/mfa/webauthn/register/complete
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "credential": { ... }
}

Agent Authentication

Agents use mTLS (mutual TLS) for authentication.

Agent Registration

POST /api/v1/agents/register
Content-Type: application/json

{
  "hostname": "web-server-01",
  "os": "linux",
  "arch": "amd64",
  "version": "1.0.0",
  "enrollment_token": "optional_token"
}

Response (with enrollment token):

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "approved",
  "certificate": "-----BEGIN CERTIFICATE-----...",
  "private_key": "-----BEGIN PRIVATE KEY-----...",
  "ca_certificate": "-----BEGIN CERTIFICATE-----...",
  "reregistration_secret": "secret_for_reregistration"
}

Response (without token):

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Agent registration pending approval"
}

Certificate Renewal

Agents can renew certificates before expiry:

POST /api/v1/agents/{uuid}/renew-certificate
X-Agent-Secret: reregistration_secret

Security Best Practices

1. Store tokens securely - Never in localStorage for web apps
2. Use short-lived access tokens - 15 minutes or less
3. Rotate refresh tokens - Issue new refresh token on use
4. Enable MFA - Require for admin accounts
5. Monitor failed logins - Alert on suspicious activity
6. Use HTTPS only - Never send tokens over HTTP

Error Handling

Common Auth Errors

Error Code	Description	Action
INVALID_CREDENTIALS	Wrong username/password	Check credentials
TOKEN_EXPIRED	Access token expired	Use refresh token
TOKEN_INVALID	Malformed or tampered token	Re-authenticate
MFA_REQUIRED	MFA code needed	Prompt for code
MFA_INVALID	Wrong MFA code	Try again
ACCOUNT_LOCKED	Too many failed attempts	Wait or contact admin

Rate Limiting

Login endpoint has stricter rate limits:

• 5 attempts per 10 minutes per IP
• 10 attempts per hour per username