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

# 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](/api/providers/ownership-challenge) and include the signed result in this request.

## Request

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

<ParamField body="provider_id" type="string" required>
  Unique identifier for this provider. Use lowercase letters, digits, and hyphens (e.g. `"acme-labs"`). Must not already exist on this node.
</ParamField>

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

<ParamField body="display_name" type="string">
  Optional human-readable name shown in listings (e.g. `"Acme Labs"`).
</ParamField>

<ParamField body="ownership_challenge_id" type="string (UUID)">
  The `challenge_id` returned by [POST /v1/providers/ownership-challenges](/api/providers/ownership-challenge). Required when the node enforces ownership challenges.
</ParamField>

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

## Response

Returns the newly created `ProviderRecord` on success.

<ResponseField name="schema_version" type="integer">
  Protocol schema version. Currently `1`.
</ResponseField>

<ResponseField name="provider_id" type="string">
  The registered provider identifier.
</ResponseField>

<ResponseField name="provider_did" type="string">
  The DID associated with this provider.
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-readable display name, if provided.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"active"` for a newly registered provider.
</ResponseField>

<ResponseField name="registered_at" type="string">
  ISO 8601 timestamp of registration.
</ResponseField>

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

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