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

# Authentication

> Learn how to authenticate your API requests and understand rate limits

## Overview

The ComfyControl API uses Bearer token authentication. All API requests must include a valid API token in the Authorization header.

## Obtaining an API Token

API tokens are created and managed through the ComfyControl web dashboard:

1. Log in to your account at [https://comfycontrol.app](https://comfycontrol.app)
2. Navigate to your account settings
3. Go to the API Tokens section
4. Create a new token with a descriptive name
5. Copy the token immediately (it will only be shown once)

<Warning>
  API tokens cannot be created or managed through the API itself. Token management is only available through the web dashboard for security reasons.
</Warning>

## Token Format

API tokens follow this format:

```
cfc_abc123def456...
```

* Prefix: `cfc_` (ComfyControl identifier)
* Followed by a random alphanumeric string
* Store tokens securely and never commit them to version control

## Using Your Token

Include your API token in the `Authorization` header of every request using the Bearer scheme:

```bash theme={null}
Authorization: Bearer cfc_abc123def456...
```

**Example Request:**

```bash theme={null}
curl https://api.comfycontrol.app/v1/user \
  -H "Authorization: Bearer cfc_abc123def456..."
```

## Token Security

<AccordionGroup>
  <Accordion title="Best Practices">
    * Store tokens in environment variables, not in code
    * Use different tokens for different applications or environments
    * Rotate tokens periodically
    * Revoke tokens immediately if compromised
    * Never share tokens or commit them to repositories
  </Accordion>

  <Accordion title="Token Expiry">
    * Tokens can be configured with optional expiration dates
    * Expired tokens will return a 401 Unauthorized error
    * Create a new token before the old one expires
    * Last used timestamp is tracked for each token
  </Accordion>
</AccordionGroup>

## Rate Limiting

The ComfyControl API implements rate limiting to ensure fair usage and system stability.

### Limits

* **40 requests per 10 seconds** per IP address
* Applies to all API endpoints
* Enforced via Cloudflare

### Exceeding Rate Limits

When you exceed the rate limit:

* You'll receive a **429 Too Many Requests** response
* A **10-second cooldown period** is automatically applied
* No requests will be processed during the cooldown
* After cooldown, normal rate limits resume

**Rate Limit Response:**

```json theme={null}
{
  "status": 429,
  "message": "Rate limit exceeded"
}
```

## Authentication Errors

Common authentication-related error responses:

| Status Code | Error             | Description                                             |
| ----------- | ----------------- | ------------------------------------------------------- |
| 401         | Unauthorized      | Missing, invalid, or expired token                      |
| 403         | Forbidden         | Valid token but insufficient permissions or tier limits |
| 429         | Too Many Requests | Rate limit exceeded                                     |

**Missing Token:**

```json theme={null}
{
  "status": 401,
  "message": "Missing authorization header"
}
```

**Invalid Token:**

```json theme={null}
{
  "status": 401,
  "message": "Invalid token"
}
```

**Expired Token:**

```json theme={null}
{
  "status": 401,
  "message": "Token has expired"
}
```