# Rotate an application's widget client_secret (new secret returned once)

> rotate client secret: reference page for this CustomDomain™ API operation in the applications group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/applications/rotateClientSecret

## `POST https://api.customdomain.ai/v1/applications/{id}/client-secret:rotate`

Mints a fresh client_secret, stores only its hash, and returns the plaintext exactly once; it is never retrievable again. The old secret stops minting widget tokens (POST /tokens) immediately; already-issued widget JWTs run out their own short TTL, unless the request sends `revoke_tokens: true`, which also revokes every widget token of the application issued until now (as `tokens:revoke` does). Update the secret your server mints with before you revoke, or widgets that ask for a new token in between fail. Admin-or-above (keys:manage): a member/viewer API key is rejected with 403.

### Authentication

`apiKey`, `managementKey`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revoke_tokens` | boolean | no | Also revoke every widget token of the application issued until now. |

### Responses

| Status | Description |
| --- | --- |
| `200` | Rotated; the new client_secret is present only in this response |
| `401` | Error envelope: {code, title, details}. |
| `402` | Refused because of the workspace's billing. `billing_required`: the workspace has no active or trialing subscription (a new workspace that has not started its trial, a Free workspace past its grace period, a comp that ended, or a subscription Stripe marked unpaid or canceled). It stops a new connection, the start of a domain purchase and the first live credential (an application, an API key or a rotated client secret). Domains already connected keep working, and an owner or admin sets up billing in the console; `details` says where. A new workspace's first domain is the exception: while it has fewer pending, propagating or live connections than its free domains (ten, unless an operator set another number: `free_domains`), a connect and the start of a purchase go through (`first_domain_free`), and the next one is refused with a `title` saying a card is needed to connect more domains. Credentials still need the trial. `quota_exceeded` (connections only): a plan that is refused past its quota (Starter, and the retired Free) is at it and the deployment enforces quotas. `connections_unavailable`: what a connect-scoped widget token, the tenant's own end user, gets instead of either (and instead of `403 workspace_suspended`), with neutral wording, so the tenant's customers are never told about the tenant's billing or account. A delegated agent token gets the full wording, and `GET /billing/standing` tells it beforehand whether a new connection would be refused. |
| `403` | Error envelope: {code, title, details}. |
| `404` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `application_id` | string | yes |  |
| `client_secret` | string | yes | sk_… (mints widget JWTs; shown once, stored hashed) |
| `tokens_revoked_before` | string | no | With `revoke_tokens`, widget tokens issued before this time are refused. |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
