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

# Authentication

> Learn how to authenticate with the Imperial API

## Authentication by Tier

Imperial offers different authentication types based on your subscription tier:

<Tabs>
  <Tab title="Free & Starter">
    **Upload Keys Only** Free and Starter tiers receive an **upload key** that can only be used for
    uploading images and videos. Upload keys cannot access other API endpoints. - Limited to `POST
            /images/upload` endpoint only - Perfect for ShareX, Imperial Shot, and other custom uploaders -
    Manage in **Settings** → **Security** section
  </Tab>

  <Tab title="Pro & Business">
    **Full API Access** Pro and Business tiers get full API keys with access to all endpoints
    including uploads, deletion, listing, and management. - Access to all API endpoints - Create
    multiple API keys - **Request analytics** - Track upload latency, success rates, and performance

    * **Detailed logs** - View request history with timestamps and status codes - **Per-key
      metrics** - Monitor usage and performance by API key - Manage in **Settings** → **API Keys**
      section
  </Tab>
</Tabs>

<Info>
  **Want full API access?** [Upgrade to Pro or Business](https://shop.imperial.gay) to unlock all
  API endpoints, create multiple API keys, and access detailed request analytics.
</Info>

## Upload Keys (Free & Starter)

Upload keys are restricted authentication tokens that only allow file uploads.

### Getting Your Upload Key

1. Log into your [Dashboard](https://app.imperial.gay)
2. Navigate to **Settings** → **Security**
3. Your upload key is displayed (starts with `imperial_upload_`)
4. Click **Regenerate Upload Key** if you need a new one

<Warning>
  Regenerating your upload key will invalidate the old one. You'll need to update it in ShareX and
  other uploaders.
</Warning>

<Note>
  Upload keys don't provide request analytics or detailed logging. [Upgrade to
  Pro](https://shop.imperial.gay) to access API keys with full analytics, latency tracking, and
  request logs.
</Note>

### Using Upload Keys

```bash theme={null}
curl https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_upload_xxxxxxxxxxxxx" \
  -F "file=@image.jpg"
```

## API Keys (Pro & Business)

API keys provide full access to all Imperial endpoints.

### Creating an API Key

1. Log into your [Dashboard](https://app.imperial.gay)
2. Navigate to **Settings** → **API Keys**
3. Click **Create API Key**
4. Give your key a descriptive name
5. Copy the key immediately (it's only shown once)

<Warning>
  Store your API key securely. It starts with `imperial_live_` and provides full access to your
  account.
</Warning>

## Authentication Methods

Imperial supports two authentication methods:

### API Key (Recommended for API usage)

Include your API key in the `Authorization` header:

```bash theme={null}
curl https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -F "file=@image.jpg"
```

### JWT Token (For dashboard/web apps)

JWT tokens are obtained through login and used internally by the dashboard. For API integrations, use API keys instead.

## Base URL

All API endpoints are relative to:

```
https://api.imperial.gay
```

## Rate Limits

Rate limits depend on your subscription tier and authentication type:

| Tier     | Authentication | Requests per Minute |
| -------- | -------------- | ------------------- |
| Free     | Upload Key     | 60                  |
| Starter  | Upload Key     | 120                 |
| Pro      | API Key        | 300                 |
| Business | API Key        | 1000                |

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704639600
```

## Error Responses

Imperial uses standard HTTP status codes:

| Code | Meaning                                        |
| ---- | ---------------------------------------------- |
| 200  | Success                                        |
| 400  | Bad Request - Invalid parameters               |
| 401  | Unauthorized - Invalid or missing API key      |
| 403  | Forbidden - Insufficient permissions           |
| 404  | Not Found                                      |
| 413  | Payload Too Large - File exceeds storage limit |
| 429  | Too Many Requests - Rate limit exceeded        |
| 500  | Internal Server Error                          |

### Error Response Format

```json theme={null}
{
  "error": "Storage limit exceeded. You've used 4.8 GB of 5 GB.",
  "statusCode": 413
}
```

## CORS

The API supports CORS for browser-based applications. All origins are allowed for GET requests. POST/DELETE requests require authentication.

## Content Types

* Upload endpoints accept `multipart/form-data`
* All other endpoints accept and return `application/json`