Obtaining A Session

Prior to connecting to any API, your administrator should setup an Application identity and a Device identity (if not using two-way TLS).

Application / Client Session

A client-credentials session is used whenever your application will be interacting with the SanteDB system without user interaction. This is primarily intended for back-end processes, system integrations, etc.

To request a client-credentials session you will need:

• Your client_id and your client_secret provided by your system administrator

• Either:

  • A client certificate which is used to authenticate the node you're using, or

  • A device_id and a device_secret provided by your system administrator.

To authenticate, first, take your device credentials and encode them as a base64 payload, for example if you device id is EXAMPLE_DEVICE_NODE and the secret is qlcEtboF-H5XdK4x1t-arL5GaG4svF9TkL5a , your device authentication header would be : RVhBTVBMRV9ERVZJQ0VfTk9ERTpxbGNFdGJvRi1INVhkSzR4MXQtYXJMNUdhRzRzdkY5VGtMNWE=

Next, locate your application credentials. These are generated by your system administrator, this example will use client_id of EXAMPLE_APPLICATION with secret 4toXrw0x-SpM1K4c7D$M0OkJcA1OgW4HeOlV

Next, construct an HTTP POST request to the endpoint <root>/auth/oauth2_token , setting the X-Device-Authorization header and the appropriate OAUTH payload:

POST http://mpi-test.local:8080/auth/oauth2_token HTTP/1.1
User-Agent: Fiddler
X-Device-Authorization: BASIC RVhBTVBMRV9ERVZJQ0VfTk9ERTpxbGNFdGJvRi1INVhkSzR4MXQtYXJMNUdhRzRzdkY5VGtMNWE=
Content-Type: application/x-www-form-urlencoded
Host: mpi-test.local:8080
Content-Length: 118

grant_type=client_credentials&scope=*&client_id=EXAMPLE_APPLICATION&client_secret=4toXrw0x-SpM1K4c7D$M0OkJcA1OgW4HeOlV

The server will respond with a series of tokens:

HTTP/1.1 200 OK
Content-Length: 1307
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Date: Mon, 11 Jan 2021 17:16:03 GMT

{
     "access_token":"E878ABAE3054EB11AFFD00155D640B2349E9BDE39EBC9082EE1D45358EC838D18122DF3FC1EFE649858826108F5881C6",
     "id_token":"eyJ0eXAiOiJK...8Ou0",
     "token_type":"bearer",
     "expires_in":1799984,
     "refresh_token":"C03E7137B9998D4584325D8EA7D393F83CFD5F4FA877393BFB280FBE3D0A7A963667E676B6A1ED3357CE2A1B57742D2B"
}

Your application should store the access_token somewhere in memory as this will need to be attached to all your requests.

You can decode the id_token to get key information about the session granted such as policies, permissions, expiration time, etc.

Using the Access_Token

The access_token is attached to each subsequent request as a BEARER token session

User-Agent: Fiddler
Authorization: bearer E878ABAE3054EB11AFFD00155D640B2349E9BDE39EBC9082EE1D45358EC838D18122DF3FC1EFE649858826108F5881C6