Skip to main content

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

​
Creating API Keys

  1. Sign in to the PixelByte Dashboard
  2. Navigate to Settings > API Keys
  3. Click Create New Key
  4. Configure scopes and IP restrictions (optional)
  5. 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:
ScopeDescription
submit_jobSubmit new AI generation jobs
check_statusCheck job status and retrieve results
list_modelsList 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:
  1. Create a new API key with the same scopes
  2. Update your application to use the new key
  3. Verify the new key works in production
  4. 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 StatusError CodeDescription
401UNAUTHORIZEDNo API key provided in the request
401INVALID_API_KEYThe API key does not exist or is malformed
401API_KEY_INACTIVEThe API key has been deactivated
401API_KEY_EXPIREDThe API key has passed its expiration date
403IP_NOT_WHITELISTEDRequest IP is not in the key’s allowed IP list
403OPERATION_NOT_ALLOWEDThe 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.