Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

Authentication

Every authenticated request sends a credential as a Bearer token in the Authorization header. Registration needs no authentication, and multipart image uploads to POST /v1/images may omit it (those keyless uploads expire after 30 days). Everything else needs a credential.

Example
curl https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

Keys are hashed server-side — PixelVault never stores the raw key, so it is shown once, at creation. Get your first key from POST /v1/auth/register (see the quickstart) or the dashboard.

Credential types

CredentialFormatWhere it works
Secret keypv_live_… or pv_test_…Every public endpoint. Keep it server-side or in an agent's environment.
Publishable keypv_pub_…Multipart POST /v1/images only, from allowlisted browser origins.
Dashboard sessionJWT from signing inThe dashboard, plus video, audio, webhook, image-edit and export endpoints. It acts on the account's first project.

The prefix is only a format check: the key type and environment come from the stored key record, so a key cannot be "upgraded" by editing its prefix.

Live and test keys

pv_test_ keys are not a sandbox. A test key is a secret key on the same project as your live keys: uploads are real, stored in the same project, served from the same CDN, and count against the same quotas. The only behavioural difference is that the billing endpoints refuse test keys with 403 test_key_forbidden, so a test key can never start a checkout or open the billing portal. Use the environment as a label to tell CI or staging credentials apart from production ones, and revoke them independently.

Publishable keys

Publishable keys back browser widgets such as paste & host. Create them in the dashboard with an allowlist of 1–20 origins (bare origins; HTTPS, or http for localhost, 127.0.0.1 and ::1). A publishable key can only make multipart uploads to POST /v1/images, and only when the request's Origin exactly matches the allowlist:

RequestResult
No Origin header, or an origin not on the list403 origin_required / 403 origin_not_allowed
Key with an empty allowlist403 no_allowed_origins
JSON URL import403 url_import_forbidden
visibility=private403 private_forbidden
describe=trueUpload succeeds with describe_skipped: "secret_key_required"
Any other endpoint403 publishable_key_forbidden (video and audio: video_upload_forbidden; webhooks: webhook_management_forbidden)

Authentication errors

StatusCodeCause
401missing_api_keyNo Authorization header on an endpoint that needs one (video, audio and webhook endpoints answer unauthorized; export answers missing_credentials)
401invalid_api_keyNot a Bearer header, wrong prefix, or an unknown or revoked key. A malformed key on POST /v1/images is rejected, never downgraded to a keyless upload.
403account_suspendedThe account is suspended. The edge caches this for up to an hour.
403email_verification_requiredUnverified accounts can store up to 5 uploads; video, audio, generation and editing need a verified email.

The full list is on Errors.

Manage API keys

Manage the keys on your project from the API, so an agent can rotate its own credentials. All three endpoints need a secret key (pv_live_/pv_test_); publishable keys get 403. Reference: list, create, revoke.

# list keys: id, type, environment, label, key_prefix, created_at, last_used_at, current
GET    /v1/keys
# body (optional): { "label": "ci", "environment": "live" }
# → 201, includes the raw "api_key" ONCE
POST   /v1/keys
# revoke a key
DELETE /v1/keys/:id

Hashes and raw keys are never returned by the list. A project can hold at most 25 keys (409 key_limit_reached), and creating or revoking keys is limited to 20 changes per hour per project. Only secret keys can be revoked here (publishable keys are managed in the dashboard). A key can't revoke itself (409 cannot_revoke_current_key), so to rotate: create a new key, switch to it, then revoke the old one with the new key. The 25-key cap is exact, and a revoke only applies while the key making the request still exists, so two keys revoking each other at the same moment cannot leave the project without a key (the loser gets 409 conflict).

# 1. Create the replacement with the old key
NEW_KEY=$(curl -s -X POST https://api.pixelvault.dev/v1/keys \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci"}' | jq -r .data.api_key)

# 2. Deploy NEW_KEY, then revoke the old key using the new one
curl -X DELETE https://api.pixelvault.dev/v1/keys/key_old123 \
  -H "Authorization: Bearer $NEW_KEY"

Sign in with an emailed code

For tools and agents that already have an account but no key: a passwordless, browser-free sign-in. The first call emails a 6-digit code (valid 10 minutes, one per 60 seconds); the second exchanges it for a new secret key. It creates the account if the email is new, exactly like /v1/auth/register, and needs a mailbox you or your user can read. Reference: start, complete.

# { "email": "dev@example.com" }  → { "data": { "sent": true } }
POST /v1/auth/device/start
# { "email": "...", "code": "123456", "label": "my-agent" }
# → api_key, key_id, project_id
POST /v1/auth/device/complete

The key is shown once. Each completion adds a key (default label PixelVault Desktop; list and revoke them under Manage API keys). Pass "replace_existing": true to delete older live keys with the same label, so reconnecting does not pile them up. A code allows 3 attempts, and the auth endpoints share a limit of 5 requests per minute per IP.

Next steps