Provider Ownership Challenges and Key Verification

Use signed Ed25519 ownership challenges to prove DID control when registering a new provider or rotating a key on a Watt ServiceNet node.

When a node requires ownership challenges, you must prove that you control the private key behind your did:key DID before the node accepts a registration or key rotation. The node issues a short-lived challenge — a random nonce — that you sign with your Ed25519 private key. The signed challenge is then included in the registration or rotation request, and the node verifies the signature against the public key encoded in your DID.

When challenges are required

The node operator controls whether challenges are required via the SERVICENET_REQUIRE_PROVIDER_OWNERSHIP_CHALLENGES environment variable. Set it to 1 to enforce challenges, or leave it unset to allow open registration.

If you are connecting to a production or shared node, assume challenges are enforced — node operators may require them regardless of the default setting.

Challenge flow

Fetching a challenge by ID

If you need to inspect an issued challenge — for example, to check its expires_at or provider_id — retrieve it by ID:

curl http://127.0.0.1:8042/v1/providers/ownership-challenges/<CHALLENGE_ID>

The response is the same ProviderOwnershipChallenge object returned when the challenge was created.

Key rotation challenges

The same challenge flow applies when rotating a provider’s DID key. Request a challenge with "operation": "rotate_key" and include the provider_id of the existing provider you are updating:

curl -X POST http://127.0.0.1:8042/v1/providers/ownership-challenges \
  -H 'content-type: application/json' \
  -d '{
    "provider_id": "acme-labs",
    "provider_did": "did:key:z6MkNewKeyABCDEF...",
    "operation": "rotate_key"
  }'

Sign the returned challenge with the new key’s private key, then include the challenge ID and signature in the rotation request. See Rotate or Revoke a Provider’s DID Key for the complete rotation flow.

Challenge request fields

provider_did · string · required

The Ed25519 did:key DID you want to associate with the provider. For rotate_key operations, this is the new DID you are rotating to.

operation · string · required

The operation you intend to complete after signing. Must be "register" or "rotate_key".

provider_id · string

The provider ID to associate with this challenge. Optional for register operations — if omitted, the node generates a unique ID. Required for rotate_key operations to identify the existing provider being updated.

Challenges expire after 5 minutes (configurable via SERVICENET_PROVIDER_CHALLENGE_TTL_SECS on the node). If your challenge expires before you complete the registration or rotation, request a new one. Expired challenges are rejected with 400 Bad Request.