---
title: "Create key (secret displayed only once)"
method: POST
path: "/keys"
tags: ["Keys"]
---

# Create key (secret displayed only once)

`POST /keys`

## Request

- Base URL: `https://console-api.blockvectra.com/v1`
- URL: `https://console-api.blockvectra.com/v1/keys`
- Auth: HTTP bearer

Create an active API key; free-account default CU limits are returned by GET /plans in key_defaults and paid-account lower bounds in paid_key_minimums when published; the actual limits of a key are cu_per_sec and burst_cu on GET /keys. The new key is usable within about 5 seconds. Optional cu_cap sets a lifetime CU cap; expires_in_secs and expires_at are mutually exclusive expiration options. An expired key returns 403 key_expired; an exhausted cap returns 403 key_cap_exhausted. Rotation preserves the cap and expiration.

## Request body

- KeyCreateRequest
  - `label` string, required: 1–64 characters, without control characters.
  - `cu_cap` integer: Lifetime CU cap for this key; unlimited if omitted.
  - `expires_in_secs` integer: Seconds until expiration from current server time (converted to absolute time); mutually exclusive with `expires_at`.
  - `expires_at` string, date-time: Expiration timestamp, RFC 3339 string with timezone (`Z` or offset); must be in the future within maximum validity; mutually exclusive with `expires_in_secs`.

## Response `201`

New key and its secret (`api_key`, displayed only this once).

- KeyCreateResponse
  - `key` KeyView, required
    - `key_id` string, required
    - `label` string, required: 1–64 characters, without control characters.
    - `status` 'active' | 'disabled' | 'revoked', required
    - `cu_per_sec` integer, required: Actual per-key token bucket refill rate (CU/s), including any paid floor or higher custom limit. Effective aggregate across all chains and Data API for this key.
    - `burst_cu` integer, required: Actual per-key token bucket capacity (CU), including any paid floor or higher custom limit. Effective aggregate across all chains and Data API for this key.
    - `created_at` string, date-time, required: RFC 3339 UTC, second precision, ending in `Z` (`2026-09-26T08:00:00Z`); no fractional seconds, without `+00:00` timezone offsets.
    - `created_by` 'console' | 'operator', required: `console` for self-created by client, `operator` for created by support.
    - `revoked_at` string, date-time, required: RFC 3339 UTC, second precision, ending in `Z` (`2026-09-26T08:00:00Z`); no fractional seconds, without `+00:00` timezone offsets.
    - `replaced_by_key_id` string, nullable, required: New key created from rotation; null if never rotated.
    - `cu_cap` integer, nullable, required: Lifetime CU cap for this key; null if unlimited. Inherited by rotated new key.
    - `cu_spent` integer, required: Settled CU counted toward key cap (settled hourly; excludes unsettled usage in latest period); inherited by rotated new key.
    - `expires_at` string, date-time, required: RFC 3339 UTC, second precision, ending in `Z` (`2026-09-26T08:00:00Z`); no fractional seconds, without `+00:00` timezone offsets.
  - `api_key` string, required: Key secret, displayed only this once.

## Other responses

- `400`: Invalid label (empty, exceeding 64 chars, control characters), unknown fields; `expires_in_secs` and `expires_at` both provided or malformed; expiration not in future or exceeding maximum validity (`reason: expires_at`), `cu_cap` not an integer in 1–9007199254740991 (zero, negative, above the maximum, fractional, string, boolean or null; `reason: cu_cap`).
- `401`: Missing or invalid session (without distinguishing cause).
- `409`: Unrevoked and unexpired key limit reached, including disabled keys; error.reason is active_keys and error.limit is the effective policy limit. This check precedes the daily creation cap.
- `413`: Request body exceeds 64 KiB limit. Exceeding this limit returns 413 (`payload_too_large`).
- `429`: Rate limit exceeded, or daily key creation limit reached for account (with reason: daily_creations).
- `500`: Internal server error.

---

[API](https://skmtc.dev/blockvectra/apis/blockvectra-console-api.md) · [All operations](https://skmtc.dev/blockvectra/apis/blockvectra-console-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blockvectra/apis/blockvectra-console-api/revisions/28c91298f433?raw)