---
title: "Create a scoped API key"
method: POST
path: "/api_keys"
tags: ["API Keys"]
---

# Create a scoped API key

`POST /api_keys`

Create a new API key restricted to a subset of scopes. The returned `value` is the only
opportunity to retrieve the plaintext secret — store it securely. This endpoint does not
accept an `Idempotency-Key` header; each call creates a new key.

Callers may only grant scopes they themselves hold (scope subsetting). Unrestricted keys
may create scoped keys; scoped keys need the `api_key:create` scope. Up to 500 scoped
keys may exist per developer.

## Request body

- CreateApiKeyInput
  - `scopes` ApiKeyScope[], required — Scopes to grant the new key. Must be a non-empty array. Each scope must be one you yourself hold (scope subsetting).
  - `name` string — A human-readable label for this key, up to 100 characters. Useful for identifying the key's purpose later.

## Response `201`

The API key was created. `value` is returned exactly once.

- ApiKeyWithSecret — Returned only on key creation. `value` is the plaintext secret and is shown exactly once.
  - `id` string, uuid, required — The unique identifier for this API key.
  - `type` 'Public' | 'Private', required — Whether the key was created programmatically (Private) or via the Dashboard (Public).
  - `owner_type` 'Developer', required — The type of entity that owns the key. Always `Developer`.
  - `owner_id` string, uuid, required — The developer ID that owns the key.
  - `prefix` 'sk-live' | 'sk-test', required — The environment prefix of the key. `sk-live` in production, `sk-test` in sandbox.
  - `last_4` string, required — The last four characters of the key, shown alongside the prefix for disambiguation in audit logs.
  - `state` 'Active' | 'Deleted', required — Lifecycle state of the key.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `scopes` string[], required — The scopes authorized on this key. A single-element list containing `bridge:api_unrestricted` denotes an unrestricted key (all standard scopes). Any other list denotes a scoped key.
  - `name` string — The human-readable label for this key, if one was provided at creation.
  - `value` string, required — The plaintext secret for this API key. Store it securely — it cannot be retrieved again.

## Other responses

- `400` — Request containing missing or invalid parameters.
- `401` — Missing or invalid API key
- `500` — Unexpected error. User may try and send the request again.

---

[API](https://skmtc.net/bridge/apis/bridge-api.md) · [All operations](https://skmtc.net/bridge/apis/bridge-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bridge/bridge-api/revisions/570998bde3b5/schema)