---
title: "Issue a key"
method: POST
path: "/v1/keys"
tags: ["Account"]
---

# Issue a key

`POST /v1/keys`

## Request

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

The secret is shown once and never again. `name` is trimmed and limited to 80 characters; a blank name is not stored blank, it gets a descriptive default naming what the key can do ('read-only key' or 'ordering key'). Scopes default to ['read']; a read-only key cannot issue a key with the `order` scope (403). At most 20 active keys.

## Request body

- object
  - `name` string: A label so the key list stays readable, trimmed. Blank or omitted stores the scope-based default ('read-only key' or 'ordering key').
  - `scopes` string[]: Ordering is opt-in per key. An explicit array matching neither scope is refused (400) rather than silently issuing a read-only key.

## Response `201`

OK

- object
  - `key_id` string
  - `name` string: The effective stored name: the trimmed name sent, or the scope-based default when blank.
  - `scopes` string[]
  - `can_order` boolean
  - `key` string: The pk_live_… secret. Shown once.
  - `warning` string

## Other responses

- `400`: Malformed request. `error` is `bad_request` (with a zod `detail`), `invalid_json`, or `unknown_parameter` / `unknown_field` (with `unknown[]` and `accepted[]`).
- `401`: Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.
- `403`: `forbidden`: a read-only key cannot mint an ordering key.
- `409`: `too_many_keys`.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

[API](https://skmtc.dev/placementapi/apis/placement-api.md) · [All operations](https://skmtc.dev/placementapi/apis/placement-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placementapi/apis/placement-api/revisions/fc4e7866eaf7?raw)