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.
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
| Credential | Format | Where it works |
|---|---|---|
| Secret key | pv_live_… or pv_test_… | Every public endpoint. Keep it server-side or in an agent's environment. |
| Publishable key | pv_pub_… | Multipart POST /v1/images only, from allowlisted browser origins. |
| Dashboard session | JWT from signing in | The 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:
| Request | Result |
|---|---|
No Origin header, or an origin not on the list | 403 origin_required / 403 origin_not_allowed |
| Key with an empty allowlist | 403 no_allowed_origins |
| JSON URL import | 403 url_import_forbidden |
visibility=private | 403 private_forbidden |
describe=true | Upload succeeds with describe_skipped: "secret_key_required" |
| Any other endpoint | 403 publishable_key_forbidden (video and audio: video_upload_forbidden; webhooks: webhook_management_forbidden) |
Authentication errors
| Status | Code | Cause |
|---|---|---|
| 401 | missing_api_key | No Authorization header on an endpoint that needs one (video, audio and webhook endpoints answer unauthorized; export answers missing_credentials) |
| 401 | invalid_api_key | Not 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. |
| 403 | account_suspended | The account is suspended. The edge caches this for up to an hour. |
| 403 | email_verification_required | Unverified 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
- Errors: every error code and whether to retry.
- Paste & host: ship a publishable key in browser code.
- Upgrade from the API with a live key.