---
title: "Create a workspace API key"
method: POST
path: "/v1/api-keys"
---

# Create a workspace API key

`POST /v1/api-keys`

## Request

- Base URL: `https://api.uploadcheck.app`
- URL: `https://api.uploadcheck.app/v1/api-keys`
- Auth: HTTP bearer

Creates a bearer key for agent clients. The raw apiKey is returned once; persisted records store only a SHA-256 hash and token prefix. Operator/admin bearer keys can provision any workspace; stored workspace API keys with api_keys:write are pinned to their own workspace, owner, plan economics, and overage cap even if another workspace, owner, plan, or cap is supplied.

## Request body

- object
  - `name` string
  - `workspace_id` string
  - `owner_email` string
  - `plan_id` string
  - `included_minutes` integer
  - `plan_price_cents` integer
  - `overage_cap_cents` integer: Approved extra-minute spend cap in cents after included deterministic minutes are exhausted. Zero or omitted means block at included minutes.
  - `scopes` string[]

## Response `201`

API key created; raw apiKey is shown once.

- object
  - `apiKey` string
  - `key` ApiKeyRecord
    - `keyId` string
    - `name` string
    - `workspaceId` string
    - `ownerEmail` string, nullable
    - `provisioningId` string, nullable
    - `checkoutCustomerId` string, nullable
    - `checkoutSubscriptionId` string, nullable
    - `tokenPrefix` string
    - `scopes` string[]
    - `planId` string, nullable
    - `includedMinutes` integer, nullable
    - `planPriceCents` integer, nullable
    - `overageCapCents` integer, nullable
    - `active` boolean
    - `createdAt` string, date-time
    - `lastUsedAt` string, date-time, nullable
  - `warning` string

## Other responses

- `401`: Missing or invalid admin API key
- `403`: API key lacks api_keys:write scope

---

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