Authentication API

PixoMonitor uses JWT (JSON Web Tokens) for authentication. Access tokens expire after 15 minutes, and refresh tokens expire after 7 days.

Authentication Overview

All authenticated endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <access_token>

Session Metadata and Refresh Credentials

Requests that issue, rotate, or revoke a login session require a stable installation identifier:

The installation header is required by email verification, login session issuance, 2FA login verification/recovery, token refresh, logout, and browser authorization-code exchange. Reuse the same UUID for the lifetime of the installation.

Web clients must send requests with credentials enabled. PixoMonitor stores the rotating refresh credential in a Secure, HttpOnly, SameSite=Strict cookie and omits refreshToken from JSON responses. Non-web clients receive refreshToken in the response body and submit it in the refresh/logout request body.

Sign Up

Rate Limit: 10 requests per hour

Request Body:

Password Requirement: Minimum 8 characters.

Request Example:

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "name": "John Doe"
}

Success Response (201 Created):

{
  "message": "Registration successful. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "email_verified": false
  }
}

Error Responses:

Email Verification

Query Parameters:

Required Header: X-PixoMonitor-Installation-ID: {installation_uuid}

Success Response (200 OK):

{
  "message": "Email verified successfully",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "email_verified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "native-clients-only"
}

Resend Verification Email

Request Body:

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

Success Response (200 OK):

{
  "message": "If this email is registered, a verification link has been sent."
}

Login

Rate Limit: 5 requests per 15 minutes

Required Header: X-PixoMonitor-Installation-ID: {installation_uuid}

Request Body:

Request Example:

{
  "email": "user@example.com",
  "password": "SecurePass123"
}

Success Response (200 OK):

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "status": "ACTIVE",
    "twoFactorEnabled": false,
    "email_verified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "native-clients-only"
}

2FA Required Response (200 OK):

If the user has two-factor authentication enabled:

{
  "requires2FA": true,
  "tempToken": "eyJhbGciOiJIUzI1NiIs..."
}

Error Responses:

Two-Factor Authentication

Verify 2FA Code (Login)

Rate Limit: 10 requests per 5 minutes

Required Header: X-PixoMonitor-Installation-ID: {installation_uuid}

Request Body:

Request Example:

{
  "tempToken": "eyJhbGciOiJIUzI1NiIs...",
  "token": "123456"
}

Success Response (200 OK):

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "status": "ACTIVE",
    "twoFactorEnabled": true,
    "email_verified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "native-clients-only"
}

Setup 2FA

Headers:

Success Response (200 OK):

{
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "secret": "JBSWY3DPEHPK3PXP",
  "backupSecret": "JBSWY3DPEHPK3PXP"
}

Verify 2FA Setup

Headers:

Request Body:

{
  "token": "123456"
}

Success Response (200 OK):

{
  "enabled": true,
  "recoveryCodes": [
    "A1B2C3D4",
    "E5F6G7H8",
    "I9J0K1L2",
    "M3N4O5P6",
    "Q7R8S9T0",
    "U1V2W3X4",
    "Y5Z6A7B8",
    "C9D0E1F2",
    "G3H4I5J6",
    "K7L8M9N0"
  ]
}

Disable 2FA

Headers:

Request Body:

{
  "token": "123456"
}

Use Recovery Code

Request Body:

{
  "tempToken": "eyJhbGciOiJIUzI1NiIs...",
  "recoveryCode": "A1B2C3D4"
}

Success Response (200 OK):

{
  "user": { ... },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "remainingCodes": 9
}

Refresh Session

Required Header: X-PixoMonitor-Installation-ID: {installation_uuid}

Web clients send an empty body with credentials enabled; the refresh credential comes from the Secure HttpOnly cookie. Non-web clients send:

{
  "refreshToken": "session-id.secret"
}

The response contains a new accessToken. Non-web responses also contain the rotated refreshToken; web responses rotate the cookie instead.

Invalid, expired, revoked, reused, or installation-mismatched refresh credentials return 401 Invalid refresh token. Suspended accounts return 403 Account suspended.

Logout Current Session

Required Header: X-PixoMonitor-Installation-ID: {installation_uuid}

Web clients send an empty body with credentials enabled. Non-web clients send the current refreshToken in the request body. Success returns 204 No Content.

Logout All Sessions

Include Authorization: Bearer {access_token}. Success returns 204 No Content.

Get Current User

Headers:

Success Response (200 OK):

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "status": "ACTIVE",
    "twoFactorEnabled": false,
    "email_verified": true
  }
}

Exchange Browser Authorization Cookie

After a successful Google OAuth or SSO callback, PixoMonitor sets a short-lived Secure HttpOnly __Host-pixomonitor_oauth_code cookie and redirects the browser to /oauth/callback. The browser then sends a credentialed POST with an empty body.

Required Header: X-PixoMonitor-Installation-ID: {installation_uuid}

The endpoint reads only the HttpOnly cookie; request-body or query-string authorization codes are not accepted. On success, it clears the one-time cookie, sets the web refresh cookie, and returns an accessToken.

Token Expiration Summary

Error Response Format

All error responses follow this format:

{
  "error": "Error message here"
}

For validation errors:

{
  "errors": [
    {
      "type": "field",
      "value": "invalid-email",
      "msg": "Invalid value",
      "path": "email",
      "location": "body"
    }
  ]
}