Rotation of secrets and keys

Overview

cidaas supports two distinct rotation operations for applications, both managed on the app itself via the App Configuration API:

Rotation type	What it protects	Typical use case
Client secret	Token endpoint authentication for confidential clients	Scheduled secret rollover for web apps and M2M clients
Signing key	Per-application signing key referenced in JWKS	Key compromise or algorithm/key-length upgrade

Both operations can be performed in Integrations → Applications (Trustdesk) or via the App Configuration API endpoints described below.

---

Client secret rotation

An app holds at most two client secrets at a time: a retiring one and the current one. This lets you roll a secret over without downtime.

Prerequisites

• Admin access to Trustdesk with app write permissions (cidaas:apps_write, role APP_CREATE, APP_DELETE, or APP_MANAGER).
• The application is a confidential client (for example Regular Web App or Non-Interactive Client).

Creating the first secret

If the app has zero secrets, create one:

POST /apps-srv/apps/{clientID}/secrets
{
  "expires_at": "2026-12-31T23:59:59Z"
}

The response contains the plaintext secret once — store it immediately, it cannot be retrieved again:

{
  "success": true,
  "status": 201,
  "data": {
    "secret_id": "b1f6...",
    "client_secret": "cs_..."
  }
}

Returns 409 Conflict if the app already has one or more secrets — use rotation instead. See Create the first client secret.

Rotating the active secret

If the app already has one secret, rotate it:

POST /apps-srv/apps/{clientID}/secrets/rotate
{
  "previous_secret_expires_at": "2026-08-01T00:00:00Z",
  "new_secret_expires_at": "2027-08-01T00:00:00Z",
  "force": false
}

• previous_secret_expires_at is required and schedules when the current (soon-to-be-retiring) secret stops working. It cannot be more than 3 months in the future.
• new_secret_expires_at is optional; if set, it must be after previous_secret_expires_at.
• If the app already has two secrets (one retiring, one current), rotation is rejected with 409 unless force: true is set — in which case the oldest secret is dropped.

The response is identical in shape to creation, again returning the new plaintext secret once. See Rotate the active client secret.

Recommended workflow

1. Rotate the secret, setting previous_secret_expires_at to when the old secret should stop working.
2. Deploy the new secret to all services that authenticate with client_secret.
3. Verify token requests succeed with the new secret.
4. Once all callers are migrated (or after the previous secret's expiry), delete it — see below.

Updating or deleting a secret

PATCH /apps-srv/apps/{clientID}/secrets/{secretID}
{
  "expires_at": "2026-09-01T00:00:00Z"
}

Only expires_at can be changed; secret_id, client_secret, and issued_at are server-managed. Send expires_at: null to remove the expiry. The response never includes the plaintext secret — see Update a client secret's expiry.

DELETE /apps-srv/apps/{clientID}/secrets/{secretID}

Either the retiring or the current secret may be deleted — including the last remaining one. Returns 202 Accepted. See Delete a client secret.

---

Signing key rotation

Signing key rotation assigns a new Key ID (KID) to an application's signing key (signing_key_config). The previous key remains valid until old_key_removal_after, so existing tokens and JWKS consumers can transition safely. Because each application has its own signing key, a compromise only affects that one application.

When to rotate

• Suspected or confirmed key compromise
• Algorithm upgrade (for example, RS256 → ES256)
• Key length increase for RSA/PS algorithms

Request

POST /apps-srv/apps/{clientID}/signing-key/rotate
{
  "alg": "RS256",
  "min_key_length": 4096,
  "old_key_removal_after": "2026-08-15T00:00:00Z"
}

Field	Description	Default
alg	Target signature algorithm (RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA).	Current app key algorithm
min_key_length	Minimum key length in bits for RSA/PS algorithms. Must match an allowed length for the algorithm.	Algorithm default (typically 4096 for RSA)
old_key_removal_after	When the previous key should be removed, giving consumers time to pick up the new one.	—

Supported algorithms and key lengths

Algorithm	Allowed key lengths (bits)	Default
RS256, PS256	2048, 3072, 4096	4096
RS384, PS384	3072, 4096	4096
RS512, PS512	4096	4096
ES256	256	256
ES384	384	384
ES512	521	521
EdDSA	256	256

Response

{
  "success": true,
  "status": 200,
  "data": {
    "active_kid": "b2c3...",
    "alg": "RS256",
    "key_length": 4096
  }
}

Requires cidaas:apps_write and role APP_CREATE or APP_MANAGER. See Rotate the app's signing key.

---

Explore related topics

• App management
• Scope management
• OAuth2 flows
• Introducing Trustdesk

Need help?

For assistance, visit our Support Portal.