# SP signing-key rotation

Signing-key rotation changes one SAML connection's service-provider signing key. It does not change the encryption certificate, ACS URLs or another connection's shared default key. The backend implements scheduling and progress APIs; portal frontend integration and hosted identity-provider interoperability remain unverified.

## Stage and acknowledge

`POST /v1/connections/{conn}/sp_key_rotations` stages a fresh connection-owned key with an empty JSON object. Management mutations require a current project administrator using a CLI credential or dashboard session; a secret API key cannot authorize them. Your customer's IT admin can run the same rotation from the hosted setup portal, through a setup link with the `edit_connection` intent for that connection.

Staging preserves the current signer and publishes current and next signing certificates in metadata. Update the identity provider to trust the published overlap before testing the next key.

The notice worker submits notices to current organization IT contacts. Submission counts are not proof of delivery or acknowledgement. An authorized current IT admin acknowledges the notice in the hosted setup portal. At least one submitted notice for this exact rotation is required. This audited acknowledgement starts the wait: **720 elapsed hours**, not a calendar-month calculation. Without acknowledgement, the connection stays on its current signer.

## Test, confirm and activate

After the wait, use the rotation's `/test` operation to obtain a single-use test URL. This test signs the SAML request with the exact staged next key. It does not issue an application authorization code. An ordinary connection test is not a substitute.

The `/confirm` operation authorizes the latest passing proof for the exact connection, generation, next key and current identity-provider configuration. A newer failed test or changed identity-provider configuration invalidates the proof. `/activate` then explicitly changes this connection's current signer. Passing a test or confirming it does not automatically activate the key.

Management and portal expose `/test`, `/confirm`, `/activate`, `/rollback` and `/retire` beneath their respective `sp_key_rotations` paths. Read progress with `GET` on the base path. Use the returned generation and proof fields rather than guessing a key or generation. There is no recurring rotation interval or automatic activation.

## Rollback and retirement

After activation, metadata publishes current and prior signing certificates until explicit retirement. `/rollback` restores this connection's retained prior signer while preserving other connections. Rollback is available only while the rollback reference has not been retired.

`/retire` releases this connection's overlap and rollback right. It does **not** destroy sealed key material. Shared keys remain available to other connections.

Progress includes pending reasons and supported Doctor instructions. A retained rollback reference older than 90 days produces a warning; an unverifiable age produces a different warning. Neither warning automatically retires a key. Review the retained key and retire it only when it is no longer needed.

## Inspect progress safely

Progress exposes public certificates, phase timestamps, submission counts and eligible test proof. It does not expose notice recipients, provider metadata or private key material. Treat test URLs as credentials and keep them out of logs and analytics.

Changing IdP configuration invalidates the staged proof epoch. Staged cancellation and restart are not currently available. All serving writers and brokers must be upgraded before enabling rotation or creating signing-key archives; mixed old/new binaries and rollback to an older binary are unsafe for those archives.

See [test sign-ins and Doctor](/hosted-portal/connection-doctor/) and the [management reference](/reference/api/management/).
