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

{
  "key": "your-api-key", 
  "secret": "your-secret-key"
}

​
Request Headers

x-account-id: your-account-id

​
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.