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.
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>"
}
}
typeand the endpoint names come from the use case; add all endpoints it requires.<endpoint type>is thetypeyou used in step 3.- A service
typemust be unique within the DID document. - The endpoints it refers to must already exist (step 3).
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>
querymatches part of the name, and names that sound like it.didServiceTypeis 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)