Certificates APIs
API for managing trust relationships and certificate rotations in the Security Service Platform (SSP).
Workflow Overview: Certificate rotation is a multi-step workflow that safely distributes new certificates across all active verticals without disrupting communications. The workflow progresses through stages: preparation, distribution, switching, and cleanup.
The set of verticals involved in a rotation depends on the deployment configuration (form factor and which services are currently deployed and enabled). Verticals fall into two behaviorally distinct categories:
- With node-level detail - Trust manager tracks per-node rotation progress and reports per-node success/failure outcomes for these verticals.
- Start acknowledgment only - Rotation is initiated but actual progress is managed externally; only whether the rotation was successfully started is recorded. No per-node detail is available through this API for these verticals.
What Triggers a Rotation (background context):
There is no public API endpoint to trigger rotation. Understanding the trigger context
helps interpret the rollout_type field in status responses.
PLATFORM_CA- Triggered automatically by the platform when the root CA certificate is near expiration, or initiated via the Trust Management UI. Renewing the root CA causes all CA-signed platform certificates to be re-issued and distributed across all verticals.INGRESS- Initiated via the Trust Management UI only, when a new CA-signed ingress certificate is applied to replace the external-facing TLS certificate.
Scope of this public API: This API is read-only with respect to the rotation workflow. Use it to monitor rotation progress and clear the status after completion. It does not expose endpoints to start, pause, or cancel a rotation.
Typical Usage Sequence:
- Certificate rotation is initiated internally by the platform.
- Poll
GET /trust/trust-rollout-statusto monitor overall progress and per-vertical summaries. - When the overall status is
COMPLETED_WITH_FAILURES, usePOST /trust/trust-rollout-statuswith filter criteria to drill into specific verticals and node-level failure details. - Once the overall status reaches a terminal state (
COMPLETED_SUCCESSFULLYorCOMPLETED_WITH_FAILURES), callDELETE /trust/trust-rollout-statusto reset and clear the status, preparing the system for the next rotation.