Request an access token

To query another care organization's API, you need an access token from that organization's authorization server. Your Nuts node requests it for you: it shows the authorization server the credentials the use case requires.

Before you start

• You found the other care organization and its authServerURL (see "Find care organizations and their endpoints").
• Your care organization's wallet has the credentials the use case's policy requires. For 360-graden-clientbeeld that's the X509Credential (see "Load the credential into the wallet").
• You know the scope. The use case sets it. For 360-graden-clientbeeld it's 360-graden.

Request the token

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

{
  "authorization_server": "https://nuts.other.example/oauth2/careorg-b",
  "scope": "360-graden",
  "credentials": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://nuts.nl/credentials/v1"
      ],
      "type": ["VerifiableCredential", "NutsEmployeeCredential"],
      "credentialSubject": {
        "name": "J. de Vries",
        "roleName": "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)