<!-- Markdown twin of https://pixelvault.dev/docs/api/api-keys/ -->

[API reference](/docs/api/)

# 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](#object)
-   GET [List API keys](#list_keys)
-   POST [Create an API key](#create_key)
-   DELETE [Revoke an API key](#revoke_key)

## The API key object

The new API key.

### Properties

The API key object properties

Property

Type

Description

`id`

string

Key id, used by [`revoke_key`](/docs/api/api-keys/#revoke_key).

`api_key`

string

The raw key. Shown only in this response.

`type`

string

Always `secret`.

One of: `secret`

`environment`

string

One of: `live`, `test`

`label`

string nullable

`created_at`

string (date-time)

The API key object

```
{
  "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`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

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

Response 200

```
{
  "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`](/docs/api/api-keys/#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

`application/json`, optional

Request body

Name

Type

Required

Description

`label`

string

Optional

Optional name, trimmed; blank means none.

max length 60

`environment`

string

Optional

`live` mints a `pv_live_` key, `test` a `pv_test_` key.

One of: `live`, `test`

Default: `live`

### Responses

-   201
    
    Key created. Store `api_key` now.
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): the body is not a JSON object, `label` is not a string or is longer than 60 characters, or `environment` is not `live` or `test`.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   409
    
    [`key_limit_reached`](/docs/errors/#key_limit_reached): the project already holds 25 keys; revoke one first.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 20 key creations and revocations per hour for the project, or the per-key request limit. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
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"}'
```

Response 201

```
{
  "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`](/docs/errors/#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`](/docs/errors/#conflict). Limited to 20 key changes per hour per project. Requires a secret key.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Key id from [`list_keys`](/docs/api/api-keys/#list_keys).

### Responses

-   200
    
    Revoked
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): no secret key with this id on the project.
    
-   409
    
    [`cannot_revoke_current_key`](/docs/errors/#cannot_revoke_current_key): the request is authenticated with that key. [`conflict`](/docs/errors/#conflict): already revoked, or the calling key was revoked at the same moment; list the keys and retry.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 20 key creations and revocations per hour for the project, or the per-key request limit. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X DELETE https://api.pixelvault.dev/v1/keys/key_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "deleted": true
  }
}
```
