Rotate ICP-Brasil certificate

Prerequisite: this is the first step of the onboarding chain (certificate → readiness → connectivity-test → submit); rotate the certificate before activating it (see activateCertificate), checking readiness (see getReadiness), or submitting any operation. Performs an evidence-emitting hot-reload of the ICP-Brasil/RSFN certificate pair (T-007). The new certificate must already exist on disk under the configured base path; this endpoint only swaps the in-memory pointer and emits an audit record. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response. The response NEVER includes the private key path or key material.

POST /v1/str/certificates/rotate

Rotate ICP-Brasil certificate

cURL

curl --request POST \
  --url https://spb.sandbox.lerian.net/v1/str/certificates/rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "certificateRef": "/etc/br-spb/certs/2026-q2/icp-brasil.crt",
  "privateKeyRef": "/etc/br-spb/certs/2026-q2/icp-brasil.key",
  "reason": "Quarterly rotation per ICP-Brasil policy"
}
'

200

{
  "auditId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "certificate": {
    "certificateId": "550e8400-e29b-41d4-a716-446655440000",
    "purpose": "OUTBOUND_SIGNING",
    "readinessImpact": "NONE",
    "status": "VALID",
    "updatedAt": "2026-05-04T18:30:00Z",
    "daysUntilExpiry": 45,
    "expiresAt": "2027-05-04T18:30:00Z"
  },
  "correlationId": "req-7a3f9c2e",
  "readiness": {
    "blockers": [
      "redis: connection refused"
    ],
    "status": "READY",
    "warnings": [
      "certificate expires in 12 days"
    ]
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key. Required on every mutation.

X-TTL · string

Idempotency key TTL in seconds (overrides the service default).

Body

application/json

certificateRef · string · required

Operator-supplied reference to the new certificate material (filesystem path or secrets-manager URI), validated against the configured cert directory before any read.

Required string length: 1 - 2048

Example:

"/etc/br-spb/certs/2026-q2/icp-brasil.crt"

privateKeyRef · string · required

Operator-supplied reference to the new private-key material (filesystem path or secrets-manager URI), validated against the configured cert directory before any read.

Required string length: 1 - 2048

Example:

"/etc/br-spb/certs/2026-q2/icp-brasil.key"

reason · string

Optional operator rationale recorded in the audit evidence (max 512 chars).

Maximum string length: 512

Example:

"Quarterly rotation per ICP-Brasil policy"

Response

200

application/json

OK

auditId · string<uuid> · required

UUID of the audit record written for this rotation.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

certificate · object · required

State of the certificate after the rotation hot-reload.

Show child attributes

correlationId · string · required

Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace.

Example:

"req-7a3f9c2e"

readiness · object

Optional post-rotation readiness summary; omitted when readiness lookup is unavailable.

Show child attributes