> For the complete documentation index, see [llms.txt](https://help.santesuite.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.santesuite.org/developers/service-apis/examples/obtaining-a-session.md).

# Obtaining A Session

{% hint style="warning" %}
Prior to connecting to any API, your administrator should setup an Application identity and a Device identity (if not using two-way TLS).
{% endhint %}

## 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:

```http
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
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.

{% hint style="info" %}
You can decode the id\_token to get key information about the session granted such as policies, permissions, expiration time, etc.
{% endhint %}

## Using the Access\_Token

The access\_token is attached to each subsequent request as a BEARER token session

```http
User-Agent: Fiddler
Authorization: bearer E878ABAE3054EB11AFFD00155D640B2349E9BDE39EBC9082EE1D45358EC838D18122DF3FC1EFE649858826108F5881C6
```