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.

Was this page helpful?