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": []
}
- Store the
id: the DID of the care organization. - All keys are listed in
verificationMethod. The other lists say what a key is used for. assertionMethod: the node signs access token requests and credentials for the care organization with this key.capabilityInvocation: this key can change the DID document.
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>"
}
}
typeand the endpoint names come from the use case; add all endpoints it requires.<endpoint type>is thetypeyou used in step 2.- A service
typemust be unique within the DID document, see RFC006. - To change the service:
PUT .../internal/didman/v1/did/<care organization DID>/compoundservice/<service type>. To remove it:DELETE .../internal/didman/v1/service/<service ID>, with theidof the service in the DID document. - The endpoints it refers to must already exist (step 2).
- An endpoint doesn't have to refer to your vendor DID: it can also be the URL itself, e.g.
"fhir": "https://fhir.example.com/base". You then have to change it in every care organization DID when the URL changes.
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>
queryis required. It matches part of the name, and names that sound like it.didServiceTypeis optional: the<service type>of step 4, e.g.eOverdracht-receiverto find care organizations that can receive an eOverdracht transfer.- Each result has the organization's name and city, and its DID document. The DID is
didDocument.id. - A care organization is only returned when its DID document is active, and it has a NutsOrganizationCredential that is not expired or revoked, from an issuer you trust: see Register, find and authorize care organizations.
[
{
"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)