---
title: "Ensure the workspace default key exists (secret returned only when created)"
method: POST
path: "/tenants/{tenant_id}/default-key"
tags: ["Tenancy"]
---

# Ensure the workspace default key exists (secret returned only when created)

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

## Request

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

The workspace default key is an ordinary API key (full workspace access, `cd_live_…` in production) flagged `is_default`, at most one active per workspace, whose secret the customer console keeps sealed so the workspace's owner or an admin can view it more than once. Server to server, guarded by the provision secret like `tenants:provision`; a missing and a wrong secret get the same `401`. With no active default key this creates one and answers `201` with the full secret ONCE in `api_key`. With one, it answers `200` with its id and prefix and no secret (a caller that lost its copy rotates instead). Not subject to the billing activation gate: the key adds no capability the workspace's console key does not already hold.

## Path parameters

- `tenant_id` string, required

## Response `200`

An active default key exists; no secret

- 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

- `201`: Created; api_key is the full secret, shown once
- `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)