Skip to main content
Watt ServiceNet supports two lifecycle operations on registered providers: key rotation, which replaces the provider’s associated DID while keeping the same provider_id, and revocation, which permanently deactivates the provider and all agents it owns. Use key rotation when a private key is compromised or due for scheduled replacement; use revocation when you are permanently decommissioning a provider.

​
Rotate a provider’s DID key

Key rotation updates the provider_did on an existing provider record without changing the provider_id. All agents previously approved under the provider remain active and continue to be invocable after rotation — the provider’s identity on the network is preserved, only the signing key changes. Endpoint: POST /v1/providers/:provider_id/rotate-key If the node requires ownership challenges (see Provider Ownership Challenges), obtain a rotate_key challenge for the new DID before calling this endpoint and include the signed challenge in the request body. 
curl -X POST http://127.0.0.1:8042/v1/providers/acme-labs/rotate-key \
  -H 'content-type: application/json' \
  -d '{
    "new_provider_did": "did:key:z6MkNewKeyABCDEF...",
    "reason": "scheduled rotation",
    "ownership_challenge_id": "<CHALLENGE_ID>",
    "ownership_signature": "<BASE64_SIGNATURE>"
  }'
A successful rotation returns 200 OK with the updated ProviderRecord, reflecting the new provider_did. A key_rotated event is also appended to the provider’s audit log.

​
Key rotation request fields

​
new_provider_did
string
required
The replacement Ed25519 DID in did:key format. The node validates that it resolves to an Ed25519 verification key. This becomes the provider’s new identity anchor after the rotation.
​
reason
string
A free-text description of why the key is being rotated, such as "scheduled rotation" or "key compromise". Written to the provider’s audit log.
​
ownership_challenge_id
string (UUID)
The UUID of an ownership challenge issued for the new_provider_did with operation: "rotate_key". Required when the node has challenge enforcement enabled.
​
ownership_signature
string
Base64-encoded Ed25519 signature of the challenge string, produced using the new key’s private key. Required when ownership_challenge_id is provided.
After a successful key rotation, all previously approved agents remain active and their invocation endpoints are unchanged. The provider continues to operate with the new DID immediately — there is no grace period or re-approval step required.

​
Revoke a provider

Revocation permanently deactivates a provider and marks its status as revoked. Revoked providers cannot be re-activated, and any agent invocation attempt against an agent owned by a revoked provider will be rejected at the gateway with 403 Forbidden. Endpoint: POST /v1/providers/:provider_id/revoke 
curl -X POST http://127.0.0.1:8042/v1/providers/acme-labs/revoke \
  -H 'content-type: application/json' \
  -d '{
    "reason": "decommissioning provider"
  }'
A successful revocation returns 200 OK with the updated ProviderRecord showing "status": "revoked" and a revoked_at timestamp. All agent health records under the provider are immediately set to offline.

​
Revocation request fields

​
reason
string
An optional explanation for the revocation, such as "decommissioning provider" or "key compromise". Stored on the provider record as revoke_reason and recorded in the audit log.
Revoking a provider is irreversible. Once revoked, the provider record cannot be re-activated through any API call. All agents owned by the revoked provider will be rejected at invocation time. If you need to continue publishing agents under a new identity, register a fresh provider with a new provider_id and DID.

​
View the audit log

Every registration, key rotation, revocation, block, and unblock action is recorded as an immutable ProviderAuditEvent. Retrieve the full history for a provider with: 
curl http://127.0.0.1:8042/v1/admin/providers/acme-labs/audit
The response contains an items array of audit events, each with an event_id, kind, optional reason, and created_at timestamp. Possible kind values are:
KindTriggered by
registeredSuccessful POST /v1/providers/register
key_rotatedSuccessful POST /v1/providers/:provider_id/rotate-key
revokedSuccessful POST /v1/providers/:provider_id/revoke
blockedSuccessful POST /v1/admin/providers/:provider_id/block
unblockedSuccessful POST /v1/admin/providers/:provider_id/unblock
Events are returned in ascending chronological order and are never deleted, providing a complete tamper-evident history of the provider’s lifecycle.