CustomDomain Docs
ReferenceAPI referenceApplications

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.

POST
/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.

AuthorizationBearer <token>

Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/applications/string/client-secret:rotate" \  -H "Content-Type: application/json" \  -d '{}'
{  "application_id": "string",  "client_secret": "string",  "tokens_revoked_before": "2019-08-24T14:15:22Z"}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "billing_required",  "title": "An active subscription is needed to connect new domains.",  "details": "This workspace has not started its subscription yet. Domains that are already connected keep working. An owner or admin can set up billing at https://app.customdomain.ai/app/billing."}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}