Skip to main content

​
Authentication Methods

UTMStack API supports two authentication methods:
  1. Bearer Token Authentication: Uses username/password to obtain a Bearer token for API requests
  2. API Key Authentication: Uses an internal API key sent in request headers
Choose the authentication method that best fits your use case and security requirements.

​
Method 1: Bearer Token Authentication

​
Step 1: Authentication Request

Use the /api/authenticate endpoint to log in and receive a Bearer token.
🔧 Request Example: 
curl -X POST https://demo.utmstack.com/api/authenticate \
-H "Content-Type: application/json" \
-d '{"username":"demo","password":"your_password"}'
Make sure to replace the credentials (username and password) with the actual user credentials for your environment.

​
Step 2: Parse the Response

The response will be a JSON object containing the Bearer token, usually under the key id_token or similar, for example: 
{
  "authenticated":true,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}

​
Step 3: Use the Bearer Token

Include the token in the Authorization header when making requests to protected endpoints.
Use the /api/elasticsearch/search endpoint to test your Bearer token authentication.
Request Example: 
curl -X 'POST' \
  'https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1vIiwiYXV0aCI6IlJPTEVfQURNSU4sU...' \
  -d '[
    {
      "field": "status",
      "operator": "IS",
      "value": 2
    },
    {
      "field": "tags",
      "operator": "IS_NOT",
      "value": "False positive"
    },
    {
      "field": "@timestamp",
      "operator": "IS_BETWEEN",
      "value": [
        "now-7d",
        "now"
      ]
    }
  ]'
Response: 
{
  "severity": 3,
  "regDateRulebot": null,
  "severityLabel": "High",
  "notes": "",
  "dataType": "alertEventLog",
  "destination": {
    "country": "India",
    "accuracyRadius": 5,
    "city": "New Delhi",
    "ip": "122.176.80.250",
    "coordinates": [
      28.6320,
      77.2202
    ]
  },
  "port": 63725,
  "countryCode": "IN",
  "subProtocolCategory": "false",
  "alertEventDetailCateg": "utmstack.demo",
  "isSatelliteProvider": false,
  "ago": "Thatti Airtel Ltd. , Telangela Services",
  "user": "Administrator",
  "san": 24505
}
What happens when you don’t include the Authorization header when making requests to protected endpoints.
Request without Authorization: 
curl -X 'POST' \
  'https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "field": "status",
      "operator": "IS",
      "value": 2
    },
    {
      "field": "tags",
      "operator": "IS_NOT",
      "value": "False positive"
    },
    {
      "field": "@timestamp",
      "operator": "IS_BETWEEN",
      "value": [
        "now-7d",
        "now"
      ]
    }
  ]'
Response: 
{
  "timestamp": "2025-04-16T16:26:35.664+00:00",
  "status": 401,
  "error": "Unauthorized",
  "path": "/api/elasticsearch/search"
}

​
Method 2: API Key Authentication

Use the Utm-Internal-Key header for server-to-server authentication without requiring user credentials.
Important Security Notice: This API key is unique to each UTMStack instance and never changes. It must be kept strictly confidential and should never be shared with anyone outside your organization. Improper use or unauthorized access to this key could compromise your entire UTMStack instance. Do not modify this value in your configuration files.

​
Step 1: Obtain the API Key

To get the internal API key, you need access to your UTMStack server instance:
  1. Connect to your UTMStack server terminal
  2. Run the following command:
cat compose.yml
  1. Look for the backend: section, then under environment:, find the value:
backend:
  environment:
    INTERNAL_KEY: your_api_key_value_here
Copy the value after INTERNAL_KEY = - this is your API key for authentication.

​
Step 2: Use the API Key in Requests

Include the API key in the Utm-Internal-Key header when making requests:
Header Configuration:
  • Name: Utm-Internal-Key
  • Location: Header
  • Value: The internal key obtained from compose.yml
Request Example: 
curl -X 'POST' \
  'https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'Utm-Internal-Key: your_internal_key_value' \
  -d '[
    {
      "field": "status",
      "operator": "IS",
      "value": 2
    },
    {
      "field": "tags",
      "operator": "IS_NOT",
      "value": "False positive"
    },
    {
      "field": "@timestamp",
      "operator": "IS_BETWEEN",
      "value": [
        "now-7d",
        "now"
      ]
    }
  ]'
Keep your internal API key secure and never expose it in client-side code. This method is intended for server-to-server communication.

​
Step 3: API Key Response

When using the correct API key, you’ll receive the same successful response as with Bearer token authentication: 
{
  "severity": 3,
  "regDateRulebot": null,
  "severityLabel": "High",
  "notes": "",
  "dataType": "alertEventLog",
  "destination": {
    "country": "India",
    "accuracyRadius": 5,
    "city": "New Delhi",
    "ip": "122.176.80.250",
    "coordinates": [
      28.6320,
      77.2202
    ]
  },
  "port": 63725,
  "countryCode": "IN",
  "subProtocolCategory": "false",
  "alertEventDetailCateg": "utmstack.demo",
  "isSatelliteProvider": false,
  "ago": "Thatti Airtel Ltd. , Telangela Services",
  "user": "Administrator",
  "san": 24505
}

​
Authentication Methods Comparison

FeatureBearer TokenAPI Key (Utm-Internal-Key)
Use CaseUser-based authenticationServer-to-server communication
SecurityToken expires, user-specificLong-lived, instance-specific
SetupRequires user credentialsRequires server access
Best ForInteractive applicationsAutomated scripts, integrations
Choose Bearer Token for user-facing applications and API Key for backend integrations and automated systems.

​
Official API Documentation

UTMStack provides two official resources where developers can explore and interact with the API:

​
Interactive Swagger UI (Demo Instance)

For hands-on testing and live API interaction, you can explore the Swagger UI provided by the public UTMStack demo instance: https://demo.utmstack.com/swagger-ui/index.html
Each client instance has its own unique Swagger URL, based on how their environment is configured.
Examples:
  • https://<your-company>.utmstack.com/swagger-ui/index.html
  • https://utmstack.<your-domain>.com/swagger-ui/index.html
These tools make it easy to test endpoints, view required parameters, and understand the behavior of the platform’s APIs.