Skip to main content

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 Your vendor DID References to your endpoints, per use case

Store the DIDs in your CRM, with the customer they belong to. The node stores the DID documents and keys.

**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. Create your vendor DID

Your vendor DID is the node DID: create it and register its NutsComm endpoint as described in Registering and configuring Node DID in the Nuts node v5.4 documentation.

Use this one DID to issue all your NutsOrganizationCredentials: other vendors have to trust every issuer DID separately.

2. 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>"
}

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

4. Create a care organization DID

Create a DID for each care organization, controlled by your vendor DID:

POST <internal Nuts interface>/internal/vdr/v1/did
{
  "selfControl": false,
  "controllers": ["<vendor DID>"],
  "assertionMethod": true,
  "capabilityInvocation": false
}

Store the id of the returned DID document. The node signs access token requests and credentials for the care organization with its key (assertionMethod).

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.

5. 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>"
  }
}
  • type and the endpoint names come from the use case; add all endpoints it requires.
  • <endpoint type> is the type you used in step 3.
  • A service type must be unique within the DID document.
  • The endpoints it refers to must already exist (step 3).
**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"
  }
}

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>
  • query matches part of the name, and names that sound like it.
  • didServiceType is optional.
  • Each result has the organization's name and city, and its DID document. The DID is didDocument.id.
  • Only care organizations with a NutsOrganizationCredential from an issuer you trust are returned, see Register, find and authorize care organizations.

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)