Unpublish and Revoke an Agent from Watt ServiceNet

Remove a published agent from the Watt ServiceNet registry with a signed unpublish request. Requires provider DID ownership proof.

To remove a published agent from ServiceNet, send a signed unpublish request to POST /v1/agents/{agent_id}/unpublish. The signature over a time-bound payload proves you control the provider’s DID, ensuring that only the original publisher can remove an agent. Once unpublished, the agent record is marked as revoked and can no longer be invoked or discovered.

Build the Unpublish Request

Construct the request body with the following fields before signing:

provider_id · string · required

Your provider ID—the same one used when the agent was submitted.

provider_did · string · required

The current DID of the provider (e.g. did:key:z6Mk...). Must match the DID on record for this provider. If you have rotated your key since submission, use the current DID.

nonce · string · required

A unique random string for this request. Prevents replay attacks. Use a UUID or a cryptographically random hex string.

issued_at_ms · integer · required

Current Unix timestamp in milliseconds at the time you sign the request.

expires_at_ms · integer · required

Expiry Unix timestamp in milliseconds. The node rejects requests received after this time. A 5-minute window (issued_at_ms + 300000) is recommended.

signature · string · required

Base64-encoded Ed25519 signature over the canonical JSON of the unpublish payload. See Signing the payload below.

reason · string

Optional human-readable explanation for the removal. Stored in the audit log.

Signing the Payload

Build the canonical JSON payload, then sign it with the provider’s Ed25519 private key. The payload to sign is:

{
  "action": "unpublish_agent",
  "provider_id": "<your-provider-id>",
  "provider_did": "<your-provider-did>",
  "agent_id": "<agent-id-to-unpublish>",
  "nonce": "<unique-nonce>",
  "issued_at_ms": 1705312800000,
  "expires_at_ms": 1705313100000,
  "reason": "<optional-reason>"
}

Apply JCS (JSON Canonicalization Scheme, RFC 8785) before signing to produce a deterministic byte sequence. Base64-encode the resulting 64-byte Ed25519 signature and set it as signature in the request body.

The agent_id is taken from the URL path, not from the request body. When building the payload to sign, use the same agent_id you will pass in the request URL.

Send the Unpublish Request

POST /v1/agents/{agent_id}/unpublish with the signed body:

curl -X POST http://127.0.0.1:8042/v1/agents/stripe-agent/unpublish \
  -H 'content-type: application/json' \
  -d '{
    "provider_id": "acme-labs",
    "provider_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
    "signature": "<BASE64_ED25519_SIG>",
    "nonce": "unique-nonce-abc123",
    "issued_at_ms": 1705312800000,
    "expires_at_ms": 1705313100000,
    "reason": "decommissioning"
  }'

A successful unpublish returns 200 OK with the updated agent record:

{
  "agent_id": "stripe-agent",
  "provider_id": "acme-labs",
  "version": "0.1.0",
  "status": "revoked",
  "updated_at": "2025-01-15T12:00:00Z"
}

After Unpublishing

Once an agent is unpublished:

• Its status is set to "revoked" in the registry.
• It is no longer returned by GET /v1/agents or GET /v1/agents/{agent_id}.
• Any invocation attempt via /invoke or /invoke-async returns 404 Not Found.
• Historical execution receipts for the agent remain queryable for auditing purposes.

To re-publish the same agent ID after unpublishing, submit a new agent submission via POST /v1/agent-submissions. The new submission will go through the normal review flow.

Unpublishing is permanent on the local node. In a P2P network, other nodes may retain a cached copy of the published agent record until their registry is refreshed via gossip or a backfill sync. Peers running in open federation mode will accept re-merged records on reconnect; ensure you coordinate with peer operators if you need network-wide removal.