Skip to main content

​
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

​
username
string
required
User login name or email address
​
password
string
required
User password
​
rememberMe
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
}

​
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);

​
Status Codes

​
200
OK
Authentication successful. Token returned.
​
401
Unauthorized
Invalid username or password.
​
403
Forbidden
Login blocked (too many attempts).
​
429
Too Many Requests
Rate limit exceeded.
​
500
Internal Server Error
Unexpected issue during authentication.

​
Error Handling

Description: Invalid credentials
Resolution: Verify username/password and try again.
Description: Login temporarily blocked due to multiple failed attempts
Resolution: Wait for cooldown period or contact admin.
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 }