Create a subject

First,Each acare neworganization identity,gets withits associatedown DID(s),subject needson tothe bevendor's createdNuts node. A subject is the name you use for the tuplecare (organization,organization environment).

in

Usingall API

calls

Performto the followingNuts RESTnode's APIinternal call.API. NoteBehind thata subject, the node creates one or more DIDs (decentralized identifiers) and their keys.

Do this once per care organization, per environment.

Before you start

The Nuts node is deployed (see chapter "Deploy"). did:web is enabled by default. We recommend setting didmethods to web, so the node doesn't also create a did:nuts DID, which spec v2 use cases don't need.

Decide: generated or your own subject ID

You have to choose one of these:

Option How What you do Let the Nuts node generate the subject ID Leave out subject isin optional.the request Store the subject ID from the response in your own system, with the care organization Bring your own subject ID Set subject in the request, e.g. to the ID your system already uses for the care organization Nothing to store: you already know the ID

If you bring your own subject ID and it isn't random (e.g. a KVK number or an auto-incrementing database key), consider adding the environment at the end, e.g. 12345678-acc. The same ID then can't exist in two environments, which reduces the chance of leaking data because environments got mixed up. The examples on this page use careorg-a-acc.

Using the API

POST <internal Nuts interface>/internal/vdr/v2/subject
Content-Type: application/json

{"subject": "fooorg-careorg-a-acc"}

The response contains the subject ID and its DID documents:

{
  "subject": "careorg-a-acc",
  "documents": [
    {
      "id": "did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142",
      ...
    }
  ]
}

Using Nuts Admin

1. Log in to the organization’s Nuts AdminAdmin.

application. Click on “Identities”"Identities". Click on the plus sign on the right side.right. Enter the subject:subject itID, consists of the tenant, dash, short form of the environment (e.g. fooorg-careorg-a-acc). ThisClick will"Create actIdentity". as key

Check whenthat interactingit worked

Other parties must be able to resolve the DID from the internet. Test that with the Nuts node’s APIs for this instance. Note: as deployments are isolated, theoretically, a staticpublic keyDID couldresolver:

be

used. But havingTake the tenantDID andfrom environmentthe id field in the nameresponse reducesabove, e.g. did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142. Paste it into the possibilityUniversal ofResolver leakageat duehttps://dev.uniresolver.io/ toand mixed-upclick environments. "Resolve". ClickIt onshould “Createreturn Identity”the DID document. If it fails, check that the node's public interface is reachable from the internet through your reverse proxy (see chapter "Deploy"). The resolver fetches the document from https://nuts.example.com/iam/657f064a-ebef-4f0f-aa87-88ed32db3142/did.json, so you can also open that URL from outside your network.

You need this DID in the next step, to issue the X509Credential. To look up a subject's DIDs later, use GET <internal Nuts interface>/internal/vdr/v2/subject/careorg-a-acc.

API reference: Verifiable Data Registry (v2)