Request an access token

To accessquery APIsanother securedcare throughorganization's Nuts,API, callersyou need an access token issuedfrom bythat theorganization's OAuth2authorization Authorizationserver. Server of the API owner. This page describes how to acquire an access token.

Requesting Service Access Token

This section describes which value(s) need to be specified in the service access token request.

In the request URL:

subjectID: the ID of the local requester, which was provided by theYour Nuts node whenrequests theit subjectfor andyou: itsit DIDs was created. In the request body:

authorization_server: the OAuth2 issuer URL of the party that grants access, found in the service discovery search result. scope: specifies what resources the access token will give access to. This is specified by the use case. credentials (optional): one or more credentials to provide toshows the authorization server thatthe are not incredentials the requester'suse wallet.case Thisrequires. is

Before typicallyyou usedstart

to

provideYou an NutsEmployeeCredential tofound the authorizationother server.care Seeorganization and its authServerURL (see "Find care organizations and their endpoints"). Your care organization's wallet has the sectioncredentials belowthe foruse howcase's topolicy providerequires. this.For 360-graden-clientbeeld that's the X509Credential (see "Load the credential into the wallet"). You token_type (optional): by default, tokens are of type DPoP that mitigate token theft. Alternatively,know the scope. The use case sets it. For 360-graden-clientbeeld it's Bearer360-graden token type can be specified, but you'll be more vulnerable to MITM attacks..

Request

the

Example

token

POST <internal Nuts interface>/internal/auth/v2/<subjectID>/careorg-a-acc/request-service-access-token
Content-Type: application/json

{
  "authorization_server": "https://example.com/nuts.other.example/oauth2/hospital_x"careorg-b",
  "scope": "eOverdracht-sender"
}

Providing additional credentials

The service access token request allows you to supply credentials to the request, that are not in the subject's wallet but required for authentication. For instance, an NutsEmployeeCredential that contains information about the current logged-in user for logging purposes. These credential don't need to be signed: in that case they will be "self-attested" (e.g., the NutsEmployeeCredential); the Verifiable Presentation's signature will provide authenticity.

Example

The example below shows an example access token request with an NutsEmployeeCredential.

POST <internal Nuts interface>/internal/auth/v2/<subjectID>/request-service-access-token
Content-Type: application/json

{
  "authorization_server": "https://example.com/oauth2/hospital_x",
  "scope": "eOverdracht-sender"360-graden",
  "credentials": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://nuts.nl/credentials/v1"
      ],
      "type": ["VerifiableCredential", "NutsEmployeeCredential"],
      "credentialSubject": {
        "name": "JohnJ. Doe"de Vries",
        "roleName": "Nurse"Verpleegkundige",
        "identifier": "123456"
      }
    }
  ]
}

Field Value careorg-a-acc (in the URL) The subject ID of your care organization: the one making the request authorization_server The other care organization's authServerURL, from the Discovery Service search result scope Set by the use case credentials Credentials to present that aren't in the wallet. See below token_type Optional. DPoP (default) or Bearer. Use DPoP: a stolen DPoP token can't be used without your node's key

The user's identity: NutsEmployeeCredential

360-graden-clientbeeld requires a NutsEmployeeCredential: who is making the request, for the other party's logging. Pass it in credentials, with the logged-in user's details:

Field Value name The user's name roleName The user's role, e.g. "Verpleegkundige" identifier The user's ID in your system

You don't sign it and you leave out issuer and credentialSubject.id: the node fills them in with your care organization's DID. The node's signature on the whole request protects it.

The response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
  "token_type": "DPoP",
  "dpop_kid": "did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142#<key id>",
  "scope": "360-graden",
  "expires_in": 3600
}

Use access_token in the Authorization header when you call the other party's FHIR API. For a DPoP token, you also need a DPoP header for every request, signed with the key in dpop_kid (see "Make the FHIR call"). The node caches tokens: calling this API again returns the same token while it's valid, so you don't have to cache it yourself.

Errors

Response Meaning 400 Bad Request A parameter is wrong, or the authorization server returned an OAuth error 412 Precondition Failed Your wallet doesn't have the credentials the policy requires 502 Bad Gateway The other party's authorization server returned an error 503 Service Unavailable The other party's authorization server can't be reached

API reference: Auth (v2)