---
title: "Create root key"
method: POST
path: "/v2/rootKeys.createKey"
tags: ["rootKeys"]
---

# Create root key

`POST /v2/rootKeys.createKey`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/rootKeys.createKey`
- Auth: HTTP bearer

Creates a root key for the authenticated workspace.
Requires `unkey:v1:<workspace_id>:rootKeys/*#write`.
The created root key cannot have more permissions than the caller.

## Request body

- V2RootKeysCreateKeyRequestBody
  - `ipAllowlist` string[]: IPv4 or IPv6 addresses and CIDR ranges allowed to use this root key. Omit to inherit the calling root key's allowlist. A caller without an IP restriction creates an unrestricted key when this field is omitted. An explicit list must stay within the caller's allowed networks; a restricted caller cannot send an empty list.
  - `name` string: Optional name for the root key.
  - `permissions` string[], required: Permissions to grant to the root key. Each permission must be within the caller's existing permissions.
  - `expires` integer, nullable: Expiration as Unix milliseconds, strictly in the future. Expiring root-key callers must provide a child expiry no later than their own. JWT admins and nonexpiring root-key callers may omit it or set null for no expiration.

## Response `200`

Root key created. Save the secret now; it cannot be retrieved later.

- V2RootKeysCreateKeyResponseBody
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2RootKeysCreateKeyResponseData, required
    - `keyId` string, required: Identifier used to manage the root key.
    - `key` string, required: Root key secret, returned only once. Store it securely.

## Other responses

- `400`: Invalid input or unsupported permission.
- `401`: Unauthorized
- `403`: Requires a workspace admin or an authorized root key, and grants within the caller's permissions.
- `500`: Internal server error, including missing or invalid root-key storage configuration.

## Changes

- **2026-10-31** `88bb238417d8`: 1 info
  - added the new optional request property `ipAllowlist`
- **2026-09-30** `2cf3cf769b2e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/rootKeys.createKey/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)