Register a Provider on the Watt ServiceNet Network

Create a provider record linked to a DID to start publishing agents on Watt ServiceNet. Covers simple registration and challenge-based registration.

A provider is your identity on Watt ServiceNet — a named, addressable entity that owns and publishes agents on the network. Every provider is anchored to an Ed25519 DID in did:key format, which means you control the identity with a private key you hold. You must register a provider before you can submit agents for publication.

Registration modes

How you register depends on how the node operator has configured the node.

Simple registration

Available when SERVICENET_REQUIRE_PROVIDER_OWNERSHIP_CHALLENGES is not set or is 0. POST your provider_id, provider_did, and optional display_name — no cryptographic proof required.

Challenge-based registration

Required when SERVICENET_REQUIRE_PROVIDER_OWNERSHIP_CHALLENGES=1 or when connecting to a node with challenge enforcement enabled. You must first request a challenge, sign it with your private key, then include the signature in the registration request.

Simple registration

When challenges are not required, register a provider with a single POST request.

curl -X POST http://127.0.0.1:8042/v1/providers/register \
  -H 'content-type: application/json' \
  -d '{
    "provider_id": "acme-labs",
    "provider_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
    "display_name": "Acme Labs"
  }'

A successful registration returns 201 Created with the new provider record:

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

provider_id must be unique across the node. If the ID is already taken, the node returns 409 Conflict. Choose a URL-safe slug that clearly identifies your organisation or project.

Challenge-based registration

When the node requires ownership challenges, you must prove control of the DID’s private key before the registration is accepted. See Provider Ownership Challenges for the complete step-by-step flow, including how to request a challenge, sign it, and include the signature in your registration request.

Request fields

provider_id · string · required

A unique, URL-safe slug that identifies this provider on the node. For example, acme-labs. Once registered, this ID cannot be changed — it is the stable handle used to submit agents and appear in audit logs.

provider_did · string · required

An Ed25519 DID key in did:key format. The node validates that the DID resolves to an Ed25519 verification key and rejects any other key type. Generate one with a standard DID toolkit or the watt-did library.

display_name · string

A human-readable name for the provider, such as "Acme Labs". Optional. Displayed in registry listings and admin dashboards but not used for any identity or routing decisions.

ownership_challenge_id · string (UUID)

The UUID of a previously issued ownership challenge. Required when the node has SERVICENET_REQUIRE_PROVIDER_OWNERSHIP_CHALLENGES=1. Obtain this by POSTing to /v1/providers/ownership-challenges first.

ownership_signature · string

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

Response fields

provider_id · string

The unique identifier for this provider, echoed back from the request.

provider_did · string

The Ed25519 DID key associated with this provider.

display_name · string

The human-readable name, if one was provided at registration.

status · string

The current lifecycle state of the provider. One of active or revoked. Newly registered providers always start as active.

registered_at · string (ISO 8601)

The UTC timestamp when the provider was created.

revoked_at · string (ISO 8601)

The UTC timestamp when the provider was revoked. Only present when status is revoked.

revoke_reason · string

The reason supplied at revocation time. Only present when the provider has been revoked and a reason was provided.

schema_version · number

The protocol schema version of this record. Currently always 1.

What to do next

Provider Ownership Challenges

Learn how to request a challenge, sign it with your Ed25519 private key, and complete challenge-based registration on a node that requires proof of DID ownership.