Register a New Provider — POST /v1/providers/register

Register a new provider with a DID. Optionally include an ownership challenge signature when the node requires proof of DID control.

Creates a new provider record and associates it with a Decentralized Identifier (DID).

If the node has SERVICENET_REQUIRE_PROVIDER_OWNERSHIP_CHALLENGES enabled (the default for database-backed deployments), you must first create an ownership challenge and include the signed result in this request.

Request

curl -X POST http://your-node:8042/v1/providers/register \
  -H 'content-type: application/json' \
  -d '{
    "provider_id": "acme-labs",
    "provider_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
    "display_name": "Acme Labs",
    "ownership_challenge_id": "b3d2e1f0-1234-5678-abcd-000000000001",
    "ownership_signature": "<BASE64_ED25519_SIGNATURE>"
  }'

Body parameters

provider_id · string · required

Unique identifier for this provider. Use lowercase letters, digits, and hyphens (e.g. "acme-labs"). Must not already exist on this node.

provider_did · string · required

The DID that controls this provider (e.g. "did:key:z6Mk…"). Must match the DID used to create the ownership challenge when challenges are required.

display_name · string

Optional human-readable name shown in listings (e.g. "Acme Labs").

ownership_challenge_id · string (UUID)

The challenge_id returned by POST /v1/providers/ownership-challenges. Required when the node enforces ownership challenges.

ownership_signature · string

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

Response

Returns the newly created ProviderRecord on success.

schema_version · integer

Protocol schema version. Currently 1.

provider_id · string

The registered provider identifier.

provider_did · string

The DID associated with this provider.

display_name · string

Human-readable display name, if provided.

status · string

Always "active" for a newly registered provider.

registered_at · string

ISO 8601 timestamp of registration.

Status codes

Code	Meaning
201 Created	Provider registered successfully.
400 Bad Request	Missing required fields, invalid DID format, or invalid ownership signature.
409 Conflict	A provider with the given provider_id already exists on this node.

Example response

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