API Keys
List, create and revoke the secret keys on a project, so an agent can rotate its own credentials. All key endpoints need a secret key (pv_live_ / pv_test_); publishable keys get 403.
The API key object
The new API key.
Properties
| Property | Type | Description |
|---|---|---|
id | string | Key id, used by |
api_key | string | The raw key. Shown only in this response. |
type | string | Always |
environment | string | |
label | string nullable | |
created_at | string (date-time) |
{
"id": "key_abc123",
"api_key": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"type": "secret",
"environment": "live",
"label": "ci",
"created_at": "2026-11-16T12:00:00.000Z"
}List API keys
GET /v1/keys
Every key on the calling key's project, oldest first, secret and publishable. Hashes and raw keys are never returned; current marks the key that made this request. Requires a secret key.
Authentication
API key, sent as Authorization: Bearer <key>.
Responses
- 200
Keys
- 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl https://api.pixelvault.dev/v1/keys \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": [
{
"id": "key_abc123",
"type": "secret",
"environment": "live",
"label": "ci",
"key_prefix": "pv_live_",
"allowed_origins": null,
"created_at": "2026-11-16T12:00:00.000Z",
"last_used_at": "2026-11-16T12:30:00.000Z",
"current": true
}
]
} Create an API key
POST /v1/keys
Mint an additional secret key for the project, so an agent can rotate its own credentials. The raw key is returned once and cannot be retrieved again; keys are hashed server-side. A project can hold at most 25 keys (exact, enforced atomically), and creating or revoking keys is limited to 20 changes per hour per project.
To rotate: create a new key, switch to it, then revoke the old one with revoke_key using the new key. Publishable keys are managed in the dashboard. Requires a secret key; an empty body is fine.
Authentication
API key, sent as Authorization: Bearer <key>.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
label | string | Optional | Optional name, trimmed; blank means none. |
environment | string | Optional |
|
Responses
- 201
Key created. Store
api_keynow. - 400
validation_error: the body is not a JSON object,labelis not a string or is longer than 60 characters, orenvironmentis notliveortest. - 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 409
key_limit_reached: the project already holds 25 keys; revoke one first. - 429
rate_limit_exceeded: more than 20 key creations and revocations per hour for the project, or the per-key request limit. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/keys \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label":"ci","environment":"live"}' {
"data": {
"id": "key_abc123",
"api_key": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"type": "secret",
"environment": "live",
"label": "ci",
"created_at": "2026-11-16T12:00:00.000Z"
}
} Revoke an API key
DELETE /v1/keys/{id}
Permanently revoke a secret key on the project. Only secret keys can be revoked here (publishable keys are managed from the dashboard and return 404). A key cannot revoke itself (cannot_revoke_current_key), so to rotate: create a new key, switch to it, then revoke the old one with the new key.
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. Limited to 20 key changes per hour per project. Requires a secret key.
Authentication
API key, sent as Authorization: Bearer <key>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Key id from |
Responses
- 200
Revoked
- 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 404
not_found: no secret key with this id on the project. - 409
cannot_revoke_current_key: the request is authenticated with that key.conflict: already revoked, or the calling key was revoked at the same moment; list the keys and retry. - 429
rate_limit_exceeded: more than 20 key creations and revocations per hour for the project, or the per-key request limit. HonourRetry-After.
curl -X DELETE https://api.pixelvault.dev/v1/keys/key_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"deleted": true
}
}