Authentication - Imperial Documentation

Authentication by Tier

Imperial offers different authentication types based on your subscription tier:

Free & Starter
Pro & Business

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

Want full API access? Upgrade to Pro or Business to unlock all API endpoints, create multiple API keys, and access detailed request analytics.

Upload Keys (Free & Starter)

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

Getting Your Upload Key

Log into your Dashboard
Navigate to Settings → Security
Your upload key is displayed (starts with imperial_upload_)
Click Regenerate Upload Key if you need a new one

Regenerating your upload key will invalidate the old one. You’ll need to update it in ShareX and other uploaders.

Upload keys don’t provide request analytics or detailed logging. Upgrade to Pro to access API keys with full analytics, latency tracking, and request logs.

Using Upload Keys

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

Log into your Dashboard
Navigate to Settings → API Keys
Click Create API Key
Give your key a descriptive name
Copy the key immediately (it’s only shown once)

Store your API key securely. It starts with imperial_live_ and provides full access to your account.

Authentication Methods

Imperial supports two authentication methods:

API Key (Recommended for API usage)

Include your API key in the Authorization header:

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

{
  "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

​Authentication by Tier

​Upload Keys (Free & Starter)

​Getting Your Upload Key

​Using Upload Keys

​API Keys (Pro & Business)

​Creating an API Key

​Authentication Methods

​API Key (Recommended for API usage)

​JWT Token (For dashboard/web apps)

​Base URL

​Rate Limits

​Error Responses

​Error Response Format

​CORS

​Content Types

Authentication by Tier

Upload Keys (Free & Starter)

Getting Your Upload Key

Using Upload Keys

API Keys (Pro & Business)

Creating an API Key

Authentication Methods

API Key (Recommended for API usage)

JWT Token (For dashboard/web apps)

Base URL

Rate Limits

Error Responses

Error Response Format

CORS

Content Types