API User Accounts

Secure Access for Integrations and Automation

API User Accounts in Mythradon are dedicated, non-interactive accounts designed specifically for accessing the platform via its REST-based APIs. These accounts represent automated systems, integrations, or third-party applications—not individual users—and are built to support secure, controlled, and auditable interactions with the system.

Key Capabilities

API User Accounts enable administrators to:

• Authenticate external systems securely without exposing personal user credentials
• Define precise access controls using Roles and Permissions
• Track API activity separately from standard user interactions for better monitoring and troubleshooting

Access Governance

API users are governed by the same Role-based security model as regular users, ensuring a consistent and robust approach to access control. This allows administrators to carefully manage what API clients can read, write, or update—reducing security risks and maintaining system integrity.

Note

To uphold the principle of least privilege, always assign only the minimum necessary permissions when configuring roles for API users.

For guidance on setting up roles and permissions, see Role Management.

---

Best Practices for API User Management

To ensure secure and maintainable integration, follow these best practices when creating and managing API User Accounts:

Naming Conventions

• Use a clear, consistent naming pattern (e.g., api_integration_xyz, api_crm_sync).
• Include the purpose or system name in the username to aid in traceability.

Credential Security

• Store API credentials securely using a secrets manager or encrypted storage.
• Never embed API credentials in client-side code, public repositories, or unencrypted files.

Credential Rotation

• Establish a routine (e.g., every 90 days) to rotate API user passwords or tokens.
• Use automation where possible to minimize downtime during rotations.

Monitoring and Auditing

• Regularly review API user activity logs to detect unexpected behaviour or misuse.
• Disable or delete unused API accounts promptly.

---

Creating an API User

To grant external systems secure access to Mythradon, you can create a dedicated API User account. Each API User is assigned a unique API key used for authentication.

Steps to Create an API User

• Navigate to Administration → API Users via the Menu Button
• Click the Create API User button
• Fill in the required properties (see table below).
• Click Save.

Once saved, a unique API Key will be generated for the user. This key is used in REST API requests via the X-API-Key header.

API User Properties

Property	Description
User Name	A unique identifier for the API User. Use a clear naming convention to indicate the system or integration this user represents.
Is Active	Determines whether the API User account is currently active. Newly created accounts are active by default.
Teams	Used to define the Teams that the User is a member of. This field allows for multiple Teams to be selected.
Default Team	Team considered to be the User's Default Team.
Roles	Used to define the Roles that the User is a member of. This field allows for multiple Roles to be selected.
Authentication Method	Specifies the method used to authenticate API requests. Supported options are: API Key or HMAC.

---

Authentication Methods: API Key vs HMAC

Mythradon supports two methods for authenticating API Users:

Method	Description
API Key	Simple token-based authentication. The API Key is sent with each request in the X-API-Key header.
HMAC	A more secure method using a hashed message authentication code (HMAC). Each request must be signed with a secret key using a cryptographic hash function.

---

API Key Authentication

Use When: Simplicity is preferred and traffic is secured by HTTPS.

After creating an API User, use the generated API Key to authenticate requests to the Mythradon REST API.

All requests must include the API Key in the request headers using the X-API-Key header.

🔐 Authentication Header Format

X-API-Key: your-api-key-here

---

Example: Using curl

curl -X GET https://yourdomain.example.com/api/v1/accounts \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

---

Example: Using Python (requests)

import requests

headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
}

response = requests.get("https://yourdomain.example.com/api/v1/accounts", headers=headers)
print(response.json())

---

Example: Using JavaScript (fetch)

fetch("https://yourdomain.example.com/api/v1/accounts", {
  method: "GET",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data));

---

HMAC Authentication

Use When: Additional verification is required to ensure request authenticity and prevent replay attacks.

Each request must include:

• A timestamp
• A signature generated using the HMAC secret key and request details

Method	Description
X-API-Key	The public API key associated with the user.
X-Signature	HMAC hash (e.g. SHA256) of the request.
X-Timestamp	The UTC timestamp of the request.

HMAC Authentication Examples

Python

import hashlib
import hmac
import time
import requests

api_key = "your-public-api-key"
secret = b"your-hmac-secret-key"  # must be bytes
timestamp = str(int(time.time()))

method = "GET"
path = "/api/v1/accounts"
body = ""  # empty for GET

# Create the message to sign
message = f"{timestamp}{method.upper()}{path}{body}".encode("utf-8")

# Generate HMAC SHA256 signature
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()

# Send request with headers
headers = {
    "X-API-Key": api_key,
    "X-Signature": signature,
    "X-Timestamp": timestamp,
    "Content-Type": "application/json"
}

response = requests.get("https://yourdomain.example.com/api/v1/accounts", headers=headers)
print(response.json())

PHP

<?php

$apiKey = "your-public-api-key";
$secret = "your-hmac-secret-key"; // secret key as a string
$timestamp = time();
$method = "GET";
$path = "/api/v1/accounts";
$body = ""; // empty string for GET requests

// Construct the message to sign
$message = $timestamp . strtoupper($method) . $path . $body;

// Generate HMAC SHA256 signature
$signature = hash_hmac('sha256', $message, $secret);

// Build headers
$headers = [
    "X-API-Key: $apiKey",
    "X-Signature: $signature",
    "X-Timestamp: $timestamp",
    "Content-Type: application/json"
];

// Make the request
$url = "https://yourdomain.example.com$path";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo "Curl error: " . curl_error($ch);
} else {
    echo $response;
}
curl_close($ch);
?>

---

Security Best Practices

• Always transmit API requests over HTTPS.
• Never expose the HMAC secret publicly.
• Reject requests where the timestamp is too old (e.g., older than 5 minutes).
• Regenerate secrets if compromise is suspected.

Note

Security Reminder:

Always store API Keys securely. Never expose them in client-side code or public repositories. If you suspect a key has been compromised, regenerate it immediately.

---

See Also

• Roles

• Mythradon Bookshelf Home

• Mythradon Basics

• Mythradon Marketing
• Mythradon Sales
• Mythradon Service
• Mythradon System Administration
• Mythradon Tools

---