Rotate Key — POST /v1/providers/:provider_id/rotate-key

Update a provider’s DID key while keeping the same provider ID. Requires an ownership challenge signature when challenges are enabled.

Replaces the DID associated with an existing provider without changing its provider_id. Use this when you need to rotate cryptographic keys while preserving registry continuity.

When the node requires ownership challenges, first create a challenge with operation: "rotate_key" and provider_id set to the target provider, sign the returned challenge string, then include both fields in this request.

Request

curl -X POST http://your-node:8042/v1/providers/acme-labs/rotate-key \
  -H 'content-type: application/json' \
  -d '{
    "new_provider_did": "did:key:z6MkpTHR8VNsBxYAAWHut2GeaddA1bbm8CLcfJ4pKzvmWwLp",
    "reason": "Scheduled key rotation",
    "ownership_challenge_id": "b3d2e1f0-1234-5678-abcd-000000000002",
    "ownership_signature": "<BASE64_ED25519_SIGNATURE>"
  }'

Path parameters

provider_id · string · required

The identifier of the provider whose DID you are rotating.

Body parameters

new_provider_did · string · required

The new DID that will replace the current one (e.g. "did:key:z6Mk…").

reason · string

Optional human-readable reason for the rotation (e.g. "Scheduled key rotation"). Stored in the audit log.

ownership_challenge_id · string (UUID)

The challenge_id from a "rotate_key" ownership challenge. Required when the node enforces ownership challenges.

ownership_signature · string

Base64-encoded Ed25519 signature of the challenge string, signed with the private key corresponding to new_provider_did. Required when ownership_challenge_id is provided.

Response

Returns the updated ProviderRecord on success.

schema_version · integer

Protocol schema version. Currently 1.

provider_id · string

The provider identifier (unchanged by this operation).

provider_did · string

The newly registered DID.

display_name · string

Human-readable display name (unchanged by this operation).

status · string

Provider lifecycle status. Returns "active" after a successful rotation.

registered_at · string

ISO 8601 timestamp of original provider registration (unchanged).

Status codes

Code	Meaning
200 OK	Key rotated successfully. Returns the updated ProviderRecord.
400 Bad Request	Invalid DID format, invalid or expired challenge, or bad signature.
404 Not Found	No provider with the given provider_id exists.

Example response

{
  "schema_version": 1,
  "provider_id": "acme-labs",
  "provider_did": "did:key:z6MkpTHR8VNsBxYAAWHut2GeaddA1bbm8CLcfJ4pKzvmWwLp",
  "display_name": "Acme Labs",
  "status": "active",
  "registered_at": "2025-01-15T10:00:00Z"
}