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

# Update root key

`POST /v2/rootKeys.updateKey`

## Request

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

Updates a root key in the authenticated workspace.
Requires `unkey:v1:<workspace_id>:rootKeys/<key_id>#write`.
Use `rootKeys/*#write` to update any root key in the workspace.

`permissions` replaces the complete permission set. Each permission must be a supported URN
in the authenticated workspace and within the caller's permissions.
An expiring root key can only update root keys that expire no later than itself.

## Request body

- V2RootKeysUpdateKeyRequestBody
  - `ipAllowlist` string[]: Replacement IPv4 or IPv6 addresses and CIDR ranges. Omit to keep the current list. Use an empty list for unrestricted access. A restricted root-key caller can expand the target's list only within the caller's allowed networks and cannot send an empty list.
  - `keyId` string, required: Root key identifier returned by rootKeys.createKey or rootKeys.listKeys.
  - `name` string, nullable: New root key name. Set null to remove the name. Omit to keep the current name.
  - `enabled` boolean: Whether the root key can authenticate. Omit to keep the current state.
  - `permissions` string[]: Complete replacement permission set. Every permission must be a supported URN in the authenticated workspace and within the caller's permissions. Omit to keep the current permissions.

## Response `200`

Root key updated.

- V2RootKeysUpdateKeyResponseBody
  - `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` EmptyResponse, required: Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400`: Invalid request or unsupported permission.
- `401`: Authentication is required.
- `403`: The caller cannot update this root key or grant a requested permission.
- `404`: The root key was not found.
- `429`: Too many requests.
- `500`: The root key could not be updated.

## 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.updateKey/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)