---
title: "Create a new API key (one-time reveal)"
method: POST
path: "/api/v1/api-keys"
tags: ["API Keys"]
---

# Create a new API key (one-time reveal)

`POST /api/v1/api-keys`

## Request

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

Generates a new `hubq_{live|test}_…` key for the authenticated user. The `full_key` field in the response is the ONLY time you can read the token — store it immediately. Active keys are bounded per workspace by the plan (Free 1, Builder 2, Team 5, Enterprise 10, live and test together).

## Request body

- CreateApiKeyRequest
  - `name` string, required: Human-readable label
  - `allowed_cidrs` string[], nullable: IP ranges (CIDR, IPv4 or IPv6) allowed to present this key (Enterprise plan); absent or empty = every IP. A call from outside the list is refused (401).
  - `scopes` string[], nullable: Requested scopes, validated against your plan. If absent, defaults to your plan's scope set. A scope your plan does not grant is rejected (403). Grantable scopes: facts.public, screener.read (free) + facts.premium, export.write (builder and up) + export.bulk (team and up) + webhooks.manage (enterprise). `admin:*` is never self-grantable.
  - `plan_override` 'free' | 'pro' | 'enterprise', nullable: DEPRECATED, ignored, and no longer stored: the backing column was dropped. The key's effective plan resolves from the workspace's plan at every verification. A value sent here is still ACCEPTED rather than rejected, on purpose -- turning a request that returns 200 today into a 422 would break a public write contract for a field that already has no effect.
  - `environment` 'live' | 'test': 'test' generates a hubq_test_... key, 'live' generates hubq_live_...
  - `expires_at` string, date-time, nullable: Optional TTL. NULL = no expiry.
  - `tos_accepted` boolean, nullable: Set to true after reading https://hub-equity.com/legal/api-terms. Required from the frontend; optional for curl/SDK callers.
  - `tos_version` string, nullable: Version of the API Terms accepted (e.g. '1.0.0-draft'). Stored on the row to detect when a future update requires re-acceptance.

## Response `201`

API key created

- ApiResponseApiKeyCreatedResponse
  - `success` boolean, required
  - `data` ApiKeyCreatedResponse: Returned ONCE at POST creation — `full_key` is shown only here.
    - `id` string, uuid, required
    - `name` string, required
    - `full_key` string, required: The complete `hubq_{env}_…` token. Shown ONCE — store it securely (password manager). It cannot be retrieved again — only revoked.
    - `key_prefix` string, required
    - `scopes` string[], required
    - `allowed_cidrs` string[], nullable
    - `plan_override` unknown, required
    - `environment` string, required
    - `expires_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
  - `error` ApiError: API error details.
    - `code` string, required
    - `message` string, required
    - `details` object, nullable
  - `meta` ApiMeta: API response metadata. Pagination fields (``page`` / ``per_page`` / ``total``) are populated on collection endpoints only. They are omitted from the payload on single-resource endpoints.
    - `timestamp` string, date-time
    - `request_id` string, nullable
    - `page` integer, nullable
    - `per_page` integer, nullable
    - `total` integer, nullable
  - `links` ApiLinks: HATEOAS-style pagination cursors. Host-relative path + query links for a collection page. Present on collection endpoints, ``null`` fields where a page doesn't exist (``next`` on the last page, ``prev`` on the first). The whole ``links`` object is omitted from single-resource responses (see ``ApiResponse`` serializer).
    - `self` string, nullable
    - `first` string, nullable
    - `prev` string, nullable
    - `next` string, nullable
    - `last` string, nullable

## Other responses

- `400`: User has no tenant
- `409`: The workspace already has as many active keys as its plan allows
- `422`: Validation Error

---

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