Authentication API

Overview

The UTMStack Authentication API issues JWT tokens to clients who provide valid credentials. Clients must authenticate using this endpoint before calling any protected resource in the UTMStack platform.

This endpoint does not require authentication. It returns a JWT access token that must be used for subsequent requests.

Endpoint Details

POST /api/authenticate

Method: POST
Content-Type: application/json
Authentication: Not required
Response: JWT token for API access

Parameters

Request Body

string

required

User login name or email address

string

required

User password

boolean

default:"false"

Optional. Keeps the session active for a longer period

JSON Schema (Request)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": { 
      "type": "string", 
      "description": "User login name" 
    },
    "password": { 
      "type": "string", 
      "description": "User password" 
    },
    "rememberMe": { 
      "type": "boolean", 
      "description": "Keep session alive" 
    }
  },
  "required": ["username", "password"]
}

Response Examples

Successful Authentication (TFA disabled)

Response
Headers

{
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImF1dGgiOiJST0xFX0FETUlOIiwiZXhwIjoxNjM0NTQ3MjAwfQ.signature",
  "authenticated": true
}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 245

TFA Challenge (TFA enabled)

{
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsInRmYSI6dHJ1ZSwiZXhwIjoxNjM0NTQ3MjAwfQ.signature",
  "authenticated": false
}

When authenticated is false, you need to complete the two-factor authentication process by providing the verification code sent to your email.

JSON Schema (Response)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id_token": { 
      "type": "string", 
      "description": "JWT bearer token" 
    },
    "authenticated": { 
      "type": "boolean", 
      "description": "Indicates whether two-factor authentication was required" 
    }
  },
  "required": ["id_token", "authenticated"]
}

Request & Response Examples

curl -X POST https://utmstack.example.com/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "MySecurePassword123",
    "rememberMe": true
  }'

{
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImF1dGgiOiJST0xFX0FETUlOIiwiZXhwIjoxNjM0NTQ3MjAwfQ.signature",
  "authenticated": true
}

Additional Code Examples

import axios from "axios";

const response = await axios.post("https://utmstack.example.com/api/authenticate", {
  username: "admin",
  password: "MySecurePassword123",
  rememberMe: true
});

console.log("Token:", response.data.id_token);

import requests

url = "https://utmstack.example.com/api/authenticate"
payload = {
    "username": "admin",
    "password": "MySecurePassword123",
    "rememberMe": True
}

response = requests.post(url, json=payload)
token = response.json()["id_token"]
print(f"Token: {token}")

Status Codes

Authentication successful. Token returned.

Unauthorized

Invalid username or password.

Forbidden

Too Many Requests

Rate limit exceeded.

Internal Server Error

Unexpected issue during authentication.

Error Handling

401 Unauthorized

Description: Invalid credentials
Resolution: Verify username/password and try again.

403 Forbidden

Description: Login temporarily blocked due to multiple failed attempts
Resolution: Wait for cooldown period or contact admin.

500 Internal Server Error

Description: Unexpected backend error
Resolution: Check logs or contact UTMStack support.

Security Considerations

Important Security Notes:

Always use HTTPS (TLS) when sending credentials
Do not store plain-text passwords or tokens locally
Implement token expiration and refresh mechanisms in clients
If TFA is enabled, a second verification code is sent by email

Using the Token

After successful authentication, include the JWT token in the Authorization header for subsequent API requests:

Authorization: Bearer <jwt_token>

Test your authentication by making a request to /api/elasticsearch/search with your Bearer token to verify it’s working correctly.

OpenAPI Specification

paths:
  /api/authenticate:
    post:
      summary: Authenticate user and issue JWT token
      operationId: authenticateUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        "200":
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        "401":
          description: Invalid credentials
        "403":
          description: Login blocked

components:
  schemas:
    LoginRequest:
      type: object
      properties:
        username: { type: string }
        password: { type: string }
        rememberMe: { type: boolean }
      required: [username, password]
    LoginResponse:
      type: object
      properties:
        id_token: { type: string }
        authenticated: { type: boolean }

Getting Started

Authentication

Alert Management

Incident Management

Analytics & Utilities

Overview

Endpoint Details

POST /api/authenticate

Parameters

Request Body

JSON Schema (Request)

Response Examples

Successful Authentication (TFA disabled)

TFA Challenge (TFA enabled)

JSON Schema (Response)

Request & Response Examples

Additional Code Examples

Status Codes

Error Handling

Security Considerations

Using the Token

OpenAPI Specification

​Overview

​Endpoint Details

POST /api/authenticate

​Parameters

​Request Body

​JSON Schema (Request)

​Response Examples

​Successful Authentication (TFA disabled)

​TFA Challenge (TFA enabled)

​JSON Schema (Response)

​Request & Response Examples

​Additional Code Examples

​Status Codes

​Error Handling

​Security Considerations

​Using the Token

​OpenAPI Specification

Overview

Endpoint Details

Parameters

Request Body

JSON Schema (Request)

Response Examples

Successful Authentication (TFA disabled)

TFA Challenge (TFA enabled)

JSON Schema (Response)

Request & Response Examples

Additional Code Examples

Status Codes

Error Handling

Security Considerations

Using the Token

OpenAPI Specification