Rotation of secrets and keys

Overview

cidaas supports two distinct rotation operations for applications. Each protects a different credential type used during OAuth2/OIDC flows:

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
App key (KID rotation)	Per-application signing key referenced in JWKS	Key compromise or algorithm/key-length upgrade

All rotation operations can be performed in Integrations → Applications (Trustdesk) or via the app-srv APIs described below.

---

Client secret rotation

Client secret rotation allows administrators to issue a new client secret while keeping the previous secret valid during a transition window. An application may hold two active secrets at the same time.

Prerequisites

Before rotating a client secret, ensure:

• You have admin access to Trustdesk (or the Admin Dashboard during transition) with app write permissions.
• The application is a confidential client with at least one active client secret (for example, Regular Web App or Non-Interactive Client).
• You have planned when the current secret should expire.

Recommended workflow

1. Create a new client secret via API or Trustdesk, setting old_client_secret_expires_at to the date when the current 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. After the old secret expires (or once all callers are migrated), delete the old secret via the delete API.

Conditions for rotation

1. Client secrets cannot be modified after creation — rotation always creates a new secret entry.
2. When creating the new secret, old_client_secret_expires_at must fall within the next three months — it cannot be more than three months in the future.
3. The new secret may have no expiration date (new_client_secret_expires_at = 0, meaning never expire).
4. If the new secret has an expiration date, it must be greater than today.

OAuth2 standard details

The following parameters come from the OAuth2 and OpenID Connect specifications.

Key	Description	Example
client_secret	OPTIONAL. A unique secret assigned to a confidential client. Must not be reused for multiple clients. Used for token endpoint authentication (OAuth 2.0 §2.3.1) and for symmetric encryption key derivation (OIDC Core §10.2).	–
client_secret_expires_at	REQUIRED if a client secret is issued. Indicates the expiration timestamp. A value of 0 means it never expires.	See note below
client_secret_issued_at	REQUIRED if a secret is issued. Defines the creation timestamp. Automatically assigned by cidaas.	See note below

Note on timestamps
The OAuth2 specification defines these values in seconds since the Unix epoch. The cidaas rotation API accepts timestamps in milliseconds since the Unix epoch (for example, 1735689600000).

Client secret APIs

All endpoints require the cidaas:apps_write or cidaas:apps_delete scope and an appropriate admin role (APP_CREATE, APP_DELETE, or APP_MANAGER).

Operation	Method	Path	Description	Link
Create client secret	POST	/apps-srv/clients/{client_id}/clientsecret	Creates a new secret and sets expiration for the old and new secrets.	View API
Delete client secret	DELETE	/apps-srv/clients/{client_id}/clientsecret/{client_secret}	Removes the old secret after migration. Provide the old secret value in the path.	View API

---

KID rotation (AppKey rotation)

AppKey rotation assigns a new Key ID (KID) to an application's signing key. The previous key remains valid for a configurable grace period so existing tokens and JWKS consumers can transition safely. If one key is compromised, only that application is affected.

This applies to the legacy client model's appKey reference exposed in JWKS and OpenID configuration.

When to use AppKey rotation

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

Query parameters

Parameter	Description	Default
keyremovaltime	Grace period before the old key is removed. Duration string such as 10m, 24h, or 10d.	10d
minlength	Minimum key length in bits for RSA/PS algorithms. Must match an allowed length for the algorithm.	Algorithm default (typically 4096 for RSA)
alg	Target signature algorithm (RS256, PS256, ES256, ES384, ES512, EdDSA). Defaults to the current algorithm.	Current app key algorithm

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

AppKey rotation API

Operation	Method	Path	Description	Link
Rotate app key	POST	/apps-srv/clients/{clientId}/appkey	Rotates the application's signing key and updates the KID in JWKS.	View API

Requires cidaas:apps_write and role APP_CREATE or APP_MANAGER.

Tenant-level app keys

The following endpoints manage tenant-wide GENERAL app keys (not per-client rotation):

Operation	Method	Path	Scope
Get tenant app key	GET	/apps-srv/appkey	cidaas:apps_read
Delete tenant app key	DELETE	/apps-srv/appkey	cidaas:apps_delete

Internal seeding endpoints (/apps-srv/appkey/verifyappkey, /unusedkeys, /privatekeys) are restricted to platform seed operations and are not intended for tenant administrators.

---

Explore related topics

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

Need help?

For assistance, visit our Support Portal.