Client Secret Rotation API
Legacy compatibility endpoint for switching the legacy-compatible primary secret.
warning
Prefer the Client API Keys API for normal operations. It supports overlapping keys and phased cutovers. This route exists for backward compatibility only.
POST /api/clients/[clientId]/rotate-secret
Generate a new primary client secret without revoking existing active keys.
Authentication
GOFA Super Admin only.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | The client ID to rotate secret for |
Request
No request body required.
Example Request
POST /api/clients/bupa/rotate-secret
Authorization: Bearer <gofa_admin_token>
Response
200 OK — Primary secret replaced successfully
Success Response
{
"success": true,
"clientSecret": "<new-secret>"
}
| Field | Type | Description |
|---|---|---|
success | boolean | Always true on success |
clientSecret | string | The newly generated secret |
Error Responses
| Status | Description |
|---|---|
| 401 | Unauthorized — missing or invalid authentication |
| 403 | Forbidden — caller is not a GOFA super admin |
| 404 | Client not found |
| 500 | Internal server error |
Behavior
- Generates a new cryptographically random secret
- Marks the new secret as the legacy-compatible primary key
- Keeps previously active keys valid until they are explicitly revoked elsewhere
- Returns the new secret in the response
Retrieving the Current Secret
Use the existing client detail endpoint with ?includeSecret=true:
GET /api/clients/bupa?includeSecret=true
Authorization: Bearer <gofa_admin_token>
The clientSecret field is only included when requested by a super admin.
Security Considerations
- Only GOFA super admins can call this legacy route
- Use the Client API Keys API for safer staged migrations
- Revoke old keys explicitly after downstream systems have switched