Skip to main content

👤 Authentication

The SecTrail CM API uses Bearer token-based authentication. To use the API endpoints, you must first obtain an access token.

Creating an API User​

Before you start using the API, you should create a user with API role:

Steps​

  1. Navigate to Users > Local Users in the SecTrail CM interface
  2. Create a new user
  3. Assign the API role to the user
  4. Save the username and password
tip

Use strong passwords for API users and store these credentials securely.

Obtaining an Authentication Token​

After creating your API user, you need to obtain an authentication token.

Endpoint​

POST /api/login

Request Body​

{
  "username": "api-user",
  "password": "your-secure-password"
}

Response​

{
  "user": "apiuser",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

Example cURL Command​

curl -X POST https://your-sectrailcm-server/api/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=api-user&password=your-secure-password"

Using the Token​

You must use the obtained authentication token in the Authorization header for all your API requests:

curl -X GET https://your-sectrailcm-server/api/endpoint \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Expiration​

  • Authentication tokens expire after a certain period
  • When your token expires, you need to obtain a new token
  • The response contains the username (user) and access token (access_token) information

Security Recommendations​

  • Never store tokens in your source code
  • Use environment variables or a secure vault
  • Secure all API requests by using HTTPS
  • Renew tokens regularly
  • Grant only necessary permissions to API users