Set up DIDs and services

In spec v1, each party is a did:nuts DID, and its endpoints are services in its DID document:

DID Who Controlled by Contains
Vendor DID You, the vendor Itself Your contact information, your endpoints (incl. NutsComm)
Care organization DID Each of your customers Itself: your node has its key. v5: your vendor DID References to your endpoints, per use case

Your vendor DID is the node DID you created when you joined the Nuts network.

Store the DIDs in your CRM (the software in which you manage your customers), with the customer they belong to. The node stores the DID documents and keys. If you run a node for your own care organization only, you are both the vendor and the care organization.

Use case design (spec v1)

The use case specifies the service types (e.g. eOverdracht-sender) and the endpoints each service must contain (e.g. oauth, fhir).

1. Add your contact information

Other node operators use it to contact you when your node or a DID document has a problem:

PUT <internal Nuts interface>/internal/didman/v1/did/<vendor DID>/contactinfo
{
  "name": "<vendor name>",
  "phone": "<phone number>",
  "email": "<email address>",
  "website": "<website URL>"
}

The node adds it to your DID document as a service of type node-contact-info.

2. Add your endpoints

Add each endpoint you host once, to your vendor DID. The care organization DIDs refer to them.

POST <internal Nuts interface>/internal/didman/v1/did/<vendor DID>/endpoint
{
  "type": "<endpoint type>",
  "endpoint": "<URL>"
}

You choose the type (e.g. production-oauth); it must be unique within the DID document. Whether endpoint is a base URL or a full URL depends on the use case. Services can share an endpoint: e.g. one oauth endpoint for all use cases.

To change or remove an endpoint:

PUT <internal Nuts interface>/internal/didman/v1/did/<vendor DID>/endpoint/<endpoint type>
DELETE <internal Nuts interface>/internal/didman/v1/did/<vendor DID>/endpoint/<endpoint type>

An endpoint that other services still refer to can't be removed.

You can also add the service of a use case to your vendor DID, as a compound service (the request of step 4, with your vendor DID). A care organization DID then refers to that whole service, instead of to each endpoint. This is what most vendors do: to change an endpoint or add one, you only change your vendor DID.

3. Create a care organization DID

Create a DID for each care organization:

POST <internal Nuts interface>/internal/vdr/v1/did

The request has no body. v5: send this body, so your vendor DID controls the DID. v6 ignores it:

{
  "selfControl": false,
  "controllers": ["<vendor DID>"],
  "assertionMethod": true,
  "capabilityInvocation": false
}

The response is the DID document:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9",
  "verificationMethod": [
    {
      "id": "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
      "controller": "did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9",
      "type": "JsonWebKey2020",
      "publicKeyJwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
    }
  ],
  "assertionMethod": ["did:nuts:2mF6KT6eiSx5y2fwTP4Y42yMUh91zGVkbu4KMARvCJz9#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw"],
  "capabilityInvocation": ["..."],
  "keyAgreement": ["..."],
  "service": []
}

To remove a care organization, deactivate its DID. This can't be undone:

DELETE <internal Nuts interface>/internal/vdr/v1/did/<care organization DID>

Then refer to your NutsComm endpoint. Without it, the care organization doesn't receive private credentials, such as NutsAuthorizationCredentials:

POST <internal Nuts interface>/internal/didman/v1/did/<care organization DID>/endpoint
{
  "type": "NutsComm",
  "endpoint": "<vendor DID>/serviceEndpoint?type=NutsComm"
}

Next, register the care organization with a NutsOrganizationCredential, so others can find it: see Register, find and authorize care organizations.

4. Enable a use case for a care organization

Add the service of the use case to the care organization DID, as a compound service: a service whose endpoints refer to the endpoints of your vendor DID.

POST <internal Nuts interface>/internal/didman/v1/did/<care organization DID>/compoundservice
{
  "type": "<service type>",
  "serviceEndpoint": {
    "<endpoint name>": "<vendor DID>/serviceEndpoint?type=<endpoint type>"
  }
}

If your vendor DID has the compound service (step 2), refer to it as a whole:

POST <internal Nuts interface>/internal/didman/v1/did/<care organization DID>/endpoint
{
  "type": "<service type>",
  "endpoint": "<vendor DID>/serviceEndpoint?type=<service type>"
}

eOverdracht

The sender adds an eOverdracht-sender service with an oauth and a fhir endpoint, see the eOverdracht leveranciersspecificatie:

{
  "type": "eOverdracht-sender",
  "serviceEndpoint": {
    "oauth": "<vendor DID>/serviceEndpoint?type=production-oauth",
    "fhir": "<vendor DID>/serviceEndpoint?type=eOverdracht-sender-fhir"
  }
}

The receiver adds an eOverdracht-receiver service with an oauth and a notification endpoint:

{
  "type": "eOverdracht-receiver",
  "serviceEndpoint": {
    "oauth": "<vendor DID>/serviceEndpoint?type=production-oauth",
    "notification": "<vendor DID>/serviceEndpoint?type=eOverdracht-receiver-notify"
  }
}

Find the endpoints of another care organization

To find care organizations by name that have the service of a use case:

GET <internal Nuts interface>/internal/didman/v1/search/organizations?query=<name>&didServiceType=<service type>
[
  {
    "didDocument": { "id": "did:nuts:...", "service": [ ... ] },
    "organization": { "name": "CareBears", "city": "CareTown" }
  }
]

Then resolve an endpoint of the service:

GET <internal Nuts interface>/internal/didman/v1/did/<DID>/compoundservice/<service type>/endpoint/<endpoint name>

The node follows the reference to the vendor DID and returns the URL: {"endpoint": "<URL>"}, or plain text with the header Accept: text/plain.

API reference: DID Manager and Verifiable Data Registry (v1)


Revision #5
Created 2026-11-17 13:06:16 UTC by Rein Krul
Updated 2026-11-18 12:49:04 UTC by Rein Krul