Skip to main content

Create a subject

Each care organization gets its own subject on the vendor's Nuts node. A subject is the name you use for the care organization in all calls to the Nuts node's internal API. Behind a 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 in 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

Keep in mind:

    The subject ID is public. It's part of your authorization server URL (https://<your node>/oauth2/<subject ID>), which is published on the Discovery Service and is in every access token. Don't use an ID you want to keep private. It may only contain letters, digits, ., _ and -.

    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": "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 Nuts Admin.
    2. Click "Identities".
    3. Click the plus sign on the right.
    4. Enter the subject ID, e.g. careorg-a-acc.
    5. Click "Create Identity".

    Check that it worked

    Other parties must be able to resolve the DID from the internet. Test that with a public DID resolver:

    1. Take the DID from the id field in the response above, e.g. did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142.
    2. Paste it into the Universal Resolver at https://dev.uniresolver.io/ and click "Resolve".
    3. It should return 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)