---
title: "Create a new API key"
method: POST
path: "/v2/api-keys"
tags: ["API keys"]
---

# Create a new API key

`POST /v2/api-keys`

Mints a new opaque API key (`sk-orq-<key_id>-<secret>`) in the workspace. The raw secret is returned ONCE in the response and is never retrievable afterwards. The stored record retains only `token_prefix` and a SHA-256 `token_hash`.

## Request body

- CreateApiKeyRequest
  - `name` string, required — Human-readable name. Required.
  - `owner` ApiKeyOwner — Owner attribution drives lifecycle. `service_account` keys are workspace-owned and outlive any individual user. `user` keys are bound to `user_id`: when the user is removed, disabled, or loses project access, the key is revoked / its scope shrinks per the cascade rules in ADR 0001.
    - `user` UserOwner
      - `user_id` string, required — User ID that owns the API key.
    - `service_account` ServiceAccountOwner
  - `project_scope` ProjectScope — Project authorization scope. Single-project or all-projects. Multi-project use cases are served by minting per-project keys or by using an all-projects key with `restricted` mode.
    - `all` AllProjects
    - `single` SingleProject
      - `project_id` string, required — Project ID this API key is scoped to.
  - `permission_mode` 'PERMISSION_MODE_UNSPECIFIED' | 'PERMISSION_MODE_ALL' | 'PERMISSION_MODE_RESTRICTED' | 'PERMISSION_MODE_READ_ONLY'
  - `access` object — Per-domain access map. Required when `permission_mode` = `PERMISSION_MODE_RESTRICTED`. See `ApiKey.access` for the full catalog of valid keys (Domain.id) and AccessLevel string values, or fetch the live catalog via the capability catalog endpoint.
  - `expires_at` string, date-time — Optional expiration. When set, the authenticate hot-path rejects the key once `expires_at` is in the past. Unset means the key never expires.
  - `mcp_access` McpAccess — McpAccess optionally restricts which MCP gateways an API key may reach at the data plane. It is orthogonal to permission_mode / access: the key must still hold the `mcp_gateway.execute` verb and project membership; McpAccess only narrows the reachable gateway set within that grant. Human sessions and keys without an McpAccess are unaffected. Semantics: - absent, or deny_all=false with an empty allowed_mcp_gateway_ids: no restriction — every gateway in the key's project scope is reachable. - deny_all=true: zero gateways are reachable. Wins over allowed_mcp_gateway_ids. - non-empty allowed_mcp_gateway_ids: only the listed gateway ids are reachable. Each id must look like `mcp_gateway_<ULID>`.
    - `deny_all` boolean — When true, the key is denied every MCP gateway regardless of allowed_mcp_gateway_ids.
    - `allowed_mcp_gateway_ids` string[] — Allow-list of MCP gateway ids (`mcp_gateway_<ULID>`) the key may reach. Ignored when deny_all is true. Empty (with deny_all=false) means no restriction.
    - `toolset_ids` string[] — Allow-list of MCP toolset ids (`mcp_toolset_<ULID>`) the key is bound to. When non-empty, the key sees and may call only the tools that are both exposed by the target gateway and members of the union of these toolsets. Empty means no toolset restriction.

## Response `200`

API key created successfully.

- ApiKeyRestResponse
  - `id` string, required
  - `name` string, required
  - `workspace_id` string, required
  - `token` string, required — Raw on create/retrieve and masked in list responses.
  - `active` boolean
  - `is_legacy` boolean
  - `source` string
  - `budget` object
  - `expiration` string, date-time
  - `projects` string[]
  - `created_by_id` string, nullable
  - `updated_by_id` string, nullable
  - `created` string, date-time
  - `updated` string, date-time
  - `consumption` number
  - `token_consumption` number
  - `requests_per_minute_consumption` number
  - `owner` object
  - `project_scope` object
  - `permission_mode` string
  - `access` object
  - `token_prefix` string
  - `status` string
  - `constraints` object
  - `mcp_access` object
  - `legacy_token_family` string
  - `legacy_key_id` string
  - `last_used_at` string, date-time

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/41c02aedc7c0/schema)