REST APIs¶

Introduction to REST APIs in Mythradon¶

Mythradon provides a powerful and secure REST API, enabling external systems and developers to interact seamlessly with both standard and custom entities within the platform. The API supports full CRUD operations—Create, Read, Update, and Delete—allowing for complete data integration and automation across a wide range of business processes.

Built using industry-standard JSON over HTTP, Mythradon's REST API is designed for simplicity, flexibility, and scalability. Whether you're integrating with external platforms, building custom applications, or automating internal workflows, the API provides robust access to the same data and capabilities available through the user interface.

Authentication & Security¶

To ensure secure access, all API requests require authentication through one of two supported models:

API Key Authentication – A straightforward method for securely identifying an API User.
HMAC Authentication – A more advanced, signature-based approach ideal for high-security environments or integrations requiring tamper protection.

Each API User is assigned specific Roles, which define their access to entities, fields, and actions. This role-based access control ensures that data access remains aligned with your organisation’s security policies.

Entity Access¶

The API supports interaction with all core and extended data models in Mythradon. This includes:

Standard Entities such as Contacts, Accounts, Leads, and Cases
Custom Entities defined specifically for your business needs

Whether you're retrieving records, updating key information, or automating workflows, the REST API gives you structured and reliable programmatic access to the data that powers Mythradon.

Getting Started¶

To begin using the Mythradon REST API, you'll need to create an API User, configure access permissions, and authenticate your requests using one of the supported authentication methods.

1. Create and Configure an API User¶

Access to the API is managed through dedicated API Users, which are configured via the Mythradon admin interface. When creating an API User, you'll:

Assign a unique username
Select an authentication method (either API Key or HMAC)
Define the appropriate Roles to control data access

🔐 Note: Roles determine which entities, fields, and operations the API User can access. Ensure the correct permissions are applied according to the purpose of the integration.

Mythradon supports two secure authentication methods:

API Key Authentication A simple token-based method where the API key is included in the request header. Suitable for most server-side integrations.
HMAC Authentication A signature-based method using a shared secret to verify the request’s authenticity. Recommended for enhanced security, especially when exposing endpoints to third parties.
Basic Authentication Regular Users of Mythradon use Basic Authentication when they login via the standard login page. This authentication method is not recommended for server-to-server integration, however this might be relevent for applications that need to access Mythradon as a spcific user and display a username/password login.

2. Make Your First API Call¶

Once your API User is configured, you can begin making requests to Mythradon's REST endpoints using standard HTTP methods (GET, POST, PUT, DELETE). All responses are returned in JSON format.

Example request using API Key authentication:

Retrieve List of Contacts

curl -X GET https://<your-Mythradon-domain>/api/v1/contacts \
  -H 'X-Api-Key: <YourApiKey>' \
  -H 'Content-Type: application/json'

The base URL for all API requests is:

https://<your-Mythradon-domain>/api/v1/

3. Explore the API¶

Mythradon provides REST access to both standard and custom entities, including:

Contacts
Organisations
Leads
Cases
Any additional custom entities configured in your instance

You can also retrieve metadata for each entity to inspect available fields, relationships, and supported operations.

4. Best Practices for Security and Monitoring¶

Use Role-based access control to limit data exposure
Rotate API keys or HMAC secrets regularly
Log API usage and errors for diagnostics and traceability
Avoid hard-coding credentials in client-side applications

Once set up, your integration can securely interact with Mythradon's powerful platform, enabling automation, data synchronisation, and seamless workflow extensions.

Authentication¶

There are several different methods to authenticate access to the Mythradon REST APIs. The appropriate method to use depends on your use-case and security standards.

Mythradon supports the following secure authentication methods:

API Key Authentication A simple token-based method where the API key is included in the request header. Suitable for most internal server-side integrations. i.e. Servers within your network under your management.
HMAC Authentication A signature-based method using a shared secret to verify the request’s authenticity. Recommended for enhanced security, especially when exposing endpoints to third parties.
Basic Authentication Regular Users of Mythradon use Basic Authentication when they login via the standard login page. This authentication method is not recommended for server-to-server integration, however this might be relevent for applications that need to access Mythradon as a spcific user and display a username/password login.

Authentication by API Key¶

The simplest method of authentication. You need to create an API User with the API Key authentication method. Apply a needed role to the API User to grant access to specific scopes.

The API Key generated for the API User is then used in a HTTP Header with every HTTP request to the Mythradon REST APIs.

``` bash "Authentication header" X-Api-Key:

Curl Example:

``` bash "Retrieve List of Contacts"
curl -X GET https://<your-Mythradon-domain>/api/v1/Contact \
-H 'X-Api-Key: <YourApiKey>' \
-H 'Content-Type: application/json' \

API Key

An API Key is obtained from the API User record when the authentication method defined on the API User is of type API Key.

HMAC Authentication¶

HMAC (Hash-based Message Authentication Code) is a cryptographic technique that uses a hash function and a secret key to verify both the integrity and authenticity of a message. It ensures that a message hasn't been tampered with during transit and that it originated from a trusted source that possesses the shared secret key.

The most secure method. You need to create an API User with the HMAC authentication method. Apply a needed role to the API User to grant access to specific scopes.

bash "Authentication header" X-Hmac-Authorization: " + base64Encode(apiKey + ':' + hashHmacSha256(method + ' /' + uri , secretKey))

where

method – GET, POST, PUT, DELETE;
uri – a request path, e.g. Lead/action/convert

Basic Authentication¶

Basic Authentication is a standard HTTP mechanism that uses a base64-encoded string containing a username and password. While less secure than other methods, it can be appropriate in controlled environments (e.g., internal networks, secured VPNs) or for quick testing purposes.

This method is not available for API Users. This is only available to standard users that have a username and password combination.

To use it:

Create a standard User
Assign the desired Roles
Use HTTP Basic Authentication headers with the API User’s username and password

Multi Factor Authentication

If the User Account has multi factor authentication enabled, additional processing is required.

API Error Codes¶

When interacting with the Mythradon REST API, errors are returned using standard HTTP status codes. Each status code helps identify the cause of the issue and guide corrective action.

Below is a summary of common error codes and their meanings:

400 – Bad Request¶

The server could not process the request due to invalid input. This typically means:

A required field was missing or left empty when creating or updating a record
The data format is incorrect or does not meet validation rules
The request body contains unexpected or malformed JSON

🛠 Tip: Check the response body for a detailed error message.

401 – Unauthorized¶

Authentication failed. This means:

The provided API key or HMAC signature is missing, invalid, or expired
The API User credentials were incorrect
Required authentication headers were not included in the request

🔐 Solution: Verify your authentication method and ensure the correct credentials are used. Refer to the Authentication section for details.

403 – Forbidden¶

The request was authenticated, but the API User does not have permission to perform the requested action or access the specified resource. This usually indicates:

The API User's assigned Roles do not allow access to this entity or action
You are trying to perform an operation restricted by access controls

🔍 Solution: Review the API User's role assignments and adjust access permissions if necessary.

404 – Not Found¶

The requested resource does not exist. Common reasons include:

The entity ID or endpoint path is incorrect
The record was deleted or never existed
A custom entity or field name was misspelled

🧭 Tip: Double-check the endpoint URL and any path parameters (e.g. record ID).

These error codes are designed to help you identify issues quickly and adjust your requests accordingly.