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. The new certificate must already exist on disk under the configured base path; this endpoint swaps the in-memory signer, adds the certificate to the keys inbound frames decrypt with (the previous one stays until restart, so frames BACEN encrypted before the activation still open) and emits an audit record. Idempotent — replaying the same X-Idempotency key with the same parsed request (member order and whitespace do not count; any other difference, such as number spelling, null for an absent field, or an unknown member, is another request) 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://api.example.com/v1/str/certificates/rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "certificateRef": "/certs/2026-q2/icp-brasil.crt",
  "privateKeyRef": "/certs/2026-q2/icp-brasil.key",
  "publicKeyRef": "spb-sign-2026-q2-pub",
  "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"
    ]
  }
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

Idempotency key. Required on every mutation.

X-TTL · string

Seconds the cached response is kept; it may only shorten IDEMPOTENCY_DEFAULT_TTL_SEC.

Corpo

application/json

certificateRef · string · obrigatório

Path to the new certificate, validated against the configured cert directory before any read. The 2048-character bound is LERIAN'S OWN, not BACEN's: a material reference is deployment configuration and never crosses an SFN wire.

Required string length: 1 - 2048

Exemplo:

"/certs/2026-q2/icp-brasil.crt"

privateKeyRef · string · obrigatório

The new private key in the configured custody: with SPB_SIGNER_KIND=file a path validated against the configured cert directory before any read, with pkcs11 the key label, with kmip the private key UID. The 2048-character bound is LERIAN'S OWN, not BACEN's: a material reference is deployment configuration and never crosses an SFN wire.

Required string length: 1 - 2048

Exemplo:

"/certs/2026-q2/icp-brasil.key"

publicKeyRef · string

With SPB_SIGNER_KIND=kmip, the UID of the new key's public half; unused by the other custodies. The 2048-character bound is LERIAN'S OWN, not BACEN's: a material reference is deployment configuration and never crosses an SFN wire.

Maximum string length: 2048

Exemplo:

"spb-sign-2026-q2-pub"

reason · string

Optional operator rationale recorded in the audit evidence. The 512-character bound is LERIAN'S OWN, not BACEN's: a rotation rationale is Lerian SPB audit evidence and never crosses an SFN wire.

Maximum string length: 512

Exemplo:

"Quarterly rotation per ICP-Brasil policy"

Resposta

200

application/json

OK

auditId · string<uuid> · obrigatório

UUID of the audit record written for this rotation.

Exemplo:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

certificate · object · obrigatório

State of the certificate after the rotation hot-reload.

Show child attributes

correlationId · string · obrigatório

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

Exemplo:

"req-7a3f9c2e"

readiness · object

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

Show child attributes