Authentication

API keys

Keys have the format sk_live_<random> or sk_test_<random> with 256 bits of cryptographically secure randomness. The platform stores only a keyed hash — if you lose a key it cannot be recovered, only rotated.

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Permissions

Each key carries a subset of these permissions:

containers.read    List and inspect containers, read usage
files.read         Download files, list items, view file info
files.write        Upload files, create folders, rename items
files.delete       Delete files and folders
files.copy         Copy items (async jobs)
files.move         Move items
metadata.read      Read custom metadata
metadata.write     Update custom metadata
storage.admin      All of the above

Requests without the required permission return HTTP 403 with error code MISSING_PERMISSION.

Key security

• Store keys in a secret manager or environment variables — never in code or client-side bundles.
• Use separate keys per application so each can be rotated independently.
• Set expiry dates and IP allowlists where your administrator supports them.
• Rotate keys periodically: your administrator issues a replacement and revokes the old key immediately.
• If a key leaks, request an immediate revocation — the old key stops working within seconds.

Failure modes

INVALID_API_KEY      401  Key missing, malformed, revoked, or unknown
EXPIRED_API_KEY      401  Key past its expiry date
MISSING_PERMISSION   403  Key lacks the permission for this operation
IP_NOT_ALLOWED       403  Request IP not in the key's allowlist
CUSTOMER_SUSPENDED   403  The customer account is suspended
RATE_LIMITED         429  Too many requests — honor Retry-After