To interact with the Mudstack API, you need to authenticate using a JSON Web Token (JWT). This token is generated using an API Key and Secret Key linked to your account.

Note: API access is only available for Pro and Enterprise customers. If you are on a different plan, please contact Mudstack support to upgrade your account.

​

Generating API Key + Secret Key

To get an API Key and Secret Key, please contact Mudstack support. Click the link below to start an email to support@mudstack.com with the subject “Generate API Key for my Mudstack Account”.

Generate API Key for my Mudstack Account

Important:

• Treat your API Key and Secret Key as sensitive credentials. Do not share them publicly or store them in unsecured locations.
• If you suspect your keys have been compromised, contact Mudstack support immediately to revoke and regenerate them.

​

Using the API Key + Secret Key

Once you have your API Key and Secret Key, you can generate a JWT. Use the following endpoint to authenticate:

POST /auth/token

​

Request Body

{
  "account_id": "your-account-id",
  "key": "your-api-key",
  "secret": "your-secret-key"
}

​

Response

"your-jwt-token"

Notes:

• The token field contains your JWT, which is valid for the duration specified in expires_in (in seconds).
• You must regenerate the JWT once it expires.

Use this token in the Authorization header for all subsequent API requests:

Authorization: Bearer your-jwt-token

​

Additional Headers for Resource Access

In addition to the Authorization header, some endpoints require additional headers to validate resource access or ownership. These headers are:

• x-account-id: Specifies the account ID associated with the request. Required for endpoints that operate at the account level.
• x-workspace-id: Specifies the workspace ID associated with the request. Required for endpoints that operate within a specific workspace.

​

Example Request with Additional Headers

Here is an example of a request that includes all necessary headers:

GET /workspace/assets/{asset_id}

​

Headers

Authorization: Bearer your-jwt-token
x-account-id: your-account-id
x-workspace-id: your-workspace-id

Best Practices:

• Always ensure the x-account-id and x-workspace-id values match the resources you are trying to access.
• Use environment variables or secure configuration files to store these values.

​

Error Handling

If the required headers are missing or invalid, the API will return an error. Common error responses include:

• 401 Unauthorized: Invalid or expired JWT.
• 403 Forbidden: Insufficient permissions or invalid resource ownership.
• 400 Bad Request: Missing or malformed headers.

​

Example Error Response

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Tips for Debugging:

• Double-check your JWT and ensure it has not expired.
• Verify that the x-account-id and x-workspace-id headers are correct and match the requested resource.

​

Security Recommendations

Keep Your JWT Secure:

• Do not expose your JWT in client-side code or public repositories.
• Store your JWT securely, such as in environment variables or secure storage mechanisms.
• Never hardcode your API Key, Secret Key, or JWT in your application code.

Rotate Your Keys Regularly:

• Periodically request to regenerate your API Key and Secret Key to minimize security risks.
• Update your application with the new keys immediately after regeneration.

For further assistance contact Mudstack Support.