> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate or Revoke a Provider DID Key on Watt ServiceNet

> Update your provider's DID key without changing your provider ID, or permanently revoke a provider from the Watt ServiceNet registry.

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](/guides/ownership-challenges)), obtain a `rotate_key` challenge for the **new** DID before calling this endpoint and include the signed challenge in the request body.

```bash theme={null}
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

<ParamField body="new_provider_did" type="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.
</ParamField>

<ParamField body="reason" type="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.
</ParamField>

<ParamField body="ownership_challenge_id" type="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.
</ParamField>

<ParamField body="ownership_signature" type="string">
  Base64-encoded Ed25519 signature of the challenge string, produced using the **new** key's private key. Required when `ownership_challenge_id` is provided.
</ParamField>

<Note>
  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.
</Note>

***

## 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`

```bash theme={null}
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

<ParamField body="reason" type="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.
</ParamField>

<Warning>
  **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.
</Warning>

***

## 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:

```bash theme={null}
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:

| Kind          | Triggered by                                               |
| ------------- | ---------------------------------------------------------- |
| `registered`  | Successful `POST /v1/providers/register`                   |
| `key_rotated` | Successful `POST /v1/providers/:provider_id/rotate-key`    |
| `revoked`     | Successful `POST /v1/providers/:provider_id/revoke`        |
| `blocked`     | Successful `POST /v1/admin/providers/:provider_id/block`   |
| `unblocked`   | Successful `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.