Authentication

All PixelByte API requests require authentication via an API key sent in the Authorization header.

Making Authenticated Requests

Include your API key as a Bearer token in the Authorization header:

curl https://api.muvi.video/v1/jobs \
  -H "Authorization: Bearer pb_your_api_key_here"

import requests

headers = {
    "Authorization": "Bearer pb_your_api_key_here"
}

response = requests.get(
    "https://api.muvi.video/v1/jobs",
    headers=headers
)

const response = await fetch("https://api.muvi.video/v1/jobs", {
  headers: {
    "Authorization": "Bearer pb_your_api_key_here"
  }
});

Creating API Keys

Sign in to the PixelByte Dashboard
Navigate to Settings > API Keys
Click Create New Key
Configure scopes and IP restrictions (optional)
Copy your key immediately

API keys are displayed only once at creation time. Store your key securely — you won’t be able to view it again.

API Key Scopes

Scopes restrict what operations an API key can perform. When creating a key, you can assign one or more scopes:

Scope	Description
`submit_job`	Submit new AI generation jobs
`check_status`	Check job status and retrieve results
`list_models`	List available models and their pricing

An empty scopes array ([]) means the key has full access to all operations. To follow the principle of least privilege, assign only the scopes your application needs.

Scope Examples

Full access key (empty array):

{
  "name": "Production Key",
  "scopes": []
}

Read-only key (status checking only):

{
  "name": "Monitoring Key",
  "scopes": ["check_status", "list_models"]
}

Job submission key (submit and check):

{
  "name": "Worker Key",
  "scopes": ["submit_job", "check_status"]
}

IP Whitelisting

Restrict API key usage to specific IP addresses for added security. When creating or updating a key, provide a list of allowed IPs:

{
  "name": "Production Key",
  "scopes": [],
  "allowedIPs": ["203.0.113.10", "198.51.100.0/24"]
}

IP whitelisting supports both individual addresses and CIDR notation for IP ranges.

Requests from non-whitelisted IPs will receive a 403 IP_NOT_WHITELISTED error.

Key Rotation

Rotate your API keys periodically to minimize the impact of key exposure. Recommended rotation workflow:

Create a new API key with the same scopes
Update your application to use the new key
Verify the new key works in production
Deactivate the old key from the dashboard

PixelByte supports multiple active keys simultaneously, allowing zero-downtime rotation.

Error Codes

Authentication and authorization errors return the following codes:

HTTP Status	Error Code	Description
401	`UNAUTHORIZED`	No API key provided in the request
401	`INVALID_API_KEY`	The API key does not exist or is malformed
401	`API_KEY_INACTIVE`	The API key has been deactivated
401	`API_KEY_EXPIRED`	The API key has passed its expiration date
403	`IP_NOT_WHITELISTED`	Request IP is not in the key’s allowed IP list
403	`OPERATION_NOT_ALLOWED`	The API key lacks the required scope for this operation

Error Response Example

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header. Provide a valid API key as a Bearer token.",
    "details": {}
  },
  "requestId": "req_abc123"
}

Security Best Practices

Use Environment Variables

Never hardcode API keys in source code. Use environment variables or a secrets manager.

Limit Scopes

Assign only the scopes each key needs. Avoid full-access keys when possible.

Enable IP Whitelisting

Restrict keys to known server IPs in production environments.

Rotate Regularly

Rotate keys on a regular schedule and immediately if a key may have been exposed.

Getting Started

Concepts

Authentication

Authentication

Making Authenticated Requests

Creating API Keys

API Key Scopes

Scope Examples

IP Whitelisting

Key Rotation

Error Codes

Error Response Example

Security Best Practices

Use Environment Variables

Limit Scopes

Enable IP Whitelisting

Rotate Regularly

​Authentication

​Making Authenticated Requests

​Creating API Keys

​API Key Scopes

​Scope Examples

​IP Whitelisting

​Key Rotation

​Error Codes

​Error Response Example

​Security Best Practices

Use Environment Variables

Limit Scopes

Enable IP Whitelisting

Rotate Regularly

Authentication

Making Authenticated Requests

Creating API Keys

API Key Scopes

Scope Examples

IP Whitelisting

Key Rotation

Error Codes

Error Response Example

Security Best Practices