---
title: "Rotate the workspace default key (new secret returned once)"
method: POST
path: "/tenants/{tenant_id}/default-key:rotate"
tags: ["Tenancy"]
---

# Rotate the workspace default key (new secret returned once)

`POST /tenants/{tenant_id}/default-key:rotate`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/tenants/{tenant_id}/default-key:rotate`
- Auth: API key in header `X-Provision-Secret`

Mints a new default key and revokes the old active one in one transaction: the old key stops authenticating at once, and there is never a moment with two active default keys or none. The workspace's other keys are untouched. With no active default key it simply creates one. Same provision secret guard as `POST /tenants/{tenant_id}/default-key`.

## Path parameters

- `tenant_id` string, required

## Response `200`

Rotated; api_key is the new full secret, shown once

- DefaultApiKey
  - `key_id` string, required
  - `prefix` string, required: The stored, non-secret prefix, for example cd_live_ab12cd34.
  - `created` boolean, required: true when this call minted the key; api_key is present only then.
  - `api_key` string: The full secret, cd_live_… or cd_test_…; shown once.

## Other responses

- `401`: Error envelope: {code, title, details}.
- `404`: Error envelope: {code, title, details}.
- `409`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)