> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating with the Mudstack API

> Learn how to securely authenticate with the Mudstack API using API keys and JSON Web Tokens (JWTs).

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](mailto:support@mudstack.com) with the subject "Generate API Key for my Mudstack Account".

[Generate API Key for my Mudstack Account](mailto:support@mudstack.com?subject=Generate%20API%20Key%20for%20my%20Mudstack%20Account)

**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

```json theme={null}
{
  "key": "your-api-key", 
  "secret": "your-secret-key"
}
```

### Request Headers

```
x-account-id: your-account-id
```

### Response

```string theme={null}
"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

```json theme={null}
{
  "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](mailto:support@mudstack.com).