> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mindrift.art/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mindrift.art/_mcp/server.

# Authentication

The Mindrift API uses API keys to authenticate requests. You can create and manage your keys in the [Mindrift dashboard](https://platform.mindrift.art/keys).

Your API keys carry full access to your account's enabled services and billing balance. Keep them secret and never share them in publicly accessible areas, client-side code or version control repositories.

## **Creating an API Key**

To start making requests to the Mindrift API, you must generate an API key from your dashboard:

![create-key-modal](https://files.buildwithfern.com/visual-editor-images/docs.mindrift.art/2026-09-10T16:42:50.410Z/authentication/create-key-modal.png "create-key-modal")

1. Sign in to your account at [platform.mindrift.art](http://platform.mindrift.art).
2. Go to **API Keys** in the navigation menu.
3. Click **Create new key**.
4. Fill in the key configuration:
   1. **Key Name**: A descriptive label to identify where the key is used (e.g. `Production Backend`, `Staging Worker`).
   2. **Service Permissions**: Select the capabilities granted to this key: *Text & Chat*, *Image*, *Video*, or *Audio & Voice*. Requests targeting services not enabled for the key are rejected with a `403 Forbidden` error.
   3. **Allowed IP Addresses **(optional): Restrict requests to specific IPv4/IPv6 addresses or CIDR blocks (e.g. `192.168.1.50, 10.0.0.0/24`). Requests from any other IP address are blocked.
   4. **Monthly Budget** (optional) : Set a spending cap in USD for this specific key. The spend counter automatically resets on the 1st of every month at 00:00 Europe/Paris time.
   5. **Expiration** (optional): Set an automatic expiration window (30 days, 90 days, or 1 year), or choose never to expire.
   6. Copy and store your secret key immediately. For security reasons, the full key secret is only displayed once and cannot be retrieved later.

All live secret keys are prefixed with `sk_`to make them easy to recognize and scan in secret detection tools.

---

## **How Bearer Authentication Works**

Every request to the Mindrift API must authenticate using standard HTTP Bearer token authentication.

### **The Authorization Header**

Instead of passing credentials through URLs, cookies or body parameters, your API key must be transmitted in the HTTP request headers using the standard `Authorization` header field.

The header value consists of two parts separated by a single space:

* The scheme identifier: the exact word `Bearer`
* Your actual secret API key

```plaintext
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### **Transport Security (HTTPS Required)**

Because Bearer authentication tokens act as secret bearer credentials (meaning anyone who possesses the token is granted access), all API traffic must be encrypted in transit.

* The Mindrift API is served strictly over HTTPS at [https://api.mindrift.art](https://api.mindrift.art).
* Requests sent over unencrypted plain HTTP (http\://) are rejected or redirected to HTTPS.
* Never disable SSL/TLS verification in your HTTP client library when communicating with the API.

### **Request Identification**

Every API response includes an `x-request-id` header containing a unique UUID. Whenever you encounter unexpected authentication failures or need support, include this request ID in your inquiry to help our team trace the exact request in our access logs.

---

## **Authentication Errors**

| **HTTP Status**         | **Error Code**            | **Explanation & Resolution**                                                                                                                                             |
| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`      | `MISSING_API_KEY`         | The `Authorization` header was not provided or was empty. Ensure your request includes `Authorization: Bearer <key>`.                                                    |
| `401 Unauthorized`      | `INVALID_API_KEY`         | The provided key does not exist or has been revoked in the dashboard. Verify that you copied the complete key string.                                                    |
| `401 Unauthorized`      | `KEY_EXPIRED`             | The key has passed its configured expiration date. Create a new key or extend the expiration date from the developer dashboard.                                          |
| `403 Forbidden`         | `IP_NOT_ALLOWED`          | The request originated from an IP address not included in the key's allowed IP list or CIDR ranges.                                                                      |
| `403 Forbidden`         | `PERMISSION_DENIED`       | The key does not have the required service permission enabled (e.g. attempting image generation with an API key that has *Image* disabled).                              |
| `429 Too Many Requests` | `MONTHLY_BUDGET_EXCEEDED` | The key has reached its configured monthly budget limit in USD. Requests will resume on the 1st of the next month at 00:00 Europe/Paris, or when the limit is increased. |
| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED`     | Your account has exceeded the allowed requests per minute (RPM) for your current tier.                                                                                   |

Authentication errors follow our standard JSON error structure:

```json
{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key provided.",
    "request_id": "7b8f9e21-4d1a-4638-9b88-51e8201bfb7c"
  }
}
```

> **Best Practices & Security**
>
> * **Keep keys on the server:** Store API keys exclusively on your secure backend servers. Never embed secret keys in frontend applications (React, Next.js client bundles, Vue, mobile apps or static web pages) as they can be extracted by anyone inspecting network traffic or application bundles.
>
> * **Use environment variables:** Inject keys into your runtime environment using environment variables (such as MINDRIFT_API_KEY) rather than hardcoding them into source files.
>
> * **Set least-privilege permissions:** When creating keys for specialized tasks (for example a microservice that only generates images), enable only the permissions that service actually needs.
>
> * **Configure IP whitelisting:** For production systems hosted on fixed servers or static IPs, restrict your API keys to those IP addresses to prevent unauthorized use if the key is accidentally leaked.
>
> * **Rotate compromised keys immediately:** If an API key is accidentally committed to a public repository or exposed in client logs, navigate to the API Keys dashboard, delete or suspend the compromised key immediately and issue a replacement.