# OAuth Token API

The OAuth Token API endpoint provides the foundation for securing all access to the SQR B2B API services.
Its purpose is to issue short-lived access tokens that prove a client’s identity and authorisation when calling protected endpoints such as `Onboarding Token` and `User Status`.
The tokens are generated using the OAuth 2.0 Client Credentials flow, ensuring that only trusted backend systems with valid credentials can obtain them.

* HTTP method: `POST`
* Path: `/v1/oauth/token`
* Grant type: `client_credentials`
* Token format: `JWT (Bearer)`


## Walkthrough

The OAuth Token flow is the first step in any interaction with the SQR B2B API.
Before a customer (Relying Party) can call protected endpoints, it must authenticate with its `Client ID` and `Client Secret` to obtain an access token.
This process uses the OAuth 2.0 Client Credentials grant, which is specifically designed for secure, machine-to-machine communication.

Once issued, the access token is presented in the `Authorization` header of subsequent requests, serving as proof of identity and authorisation.


```
Authorization: Bearer <access_token>
```

#### Request

The OAuth Token request is made as a `POST` call to the token endpoint with a **JSON-encoded** body and a `Content-Type: application/json` header.

The body must contain the client’s credentials `client_id` and `client_secret` along with the grant_type, which must be set to `client_credentials`.
This format ensures that the API can correctly authenticate the client and issue a valid access token.

##### Example

*Header*


```
{
  "Content-Type": "application/json"
  }
```

*Body*


```
 {
  "client_id": "xxxxxxx-xxxx-xxxx-xxxxxx-xxxxxxxxxx",
  "client_secret": "***********************************",
  "grant_type": "client_credentials"
  }
```

#### Response

The OAuth Token endpoint responds with a `200` OK status and a payload encoded in JSON format.
The response body contains the issued access token and related metadata.

Specifically, it includes:

* `access_token`, a signed JWT string that must be presented in the `Authorization:` Bearer header for all subsequent API requests.
* `token_type`, always Bearer, indicating the format of the issued token.
* `expires_in`, the lifetime of the token in seconds.
* `scope`, the space-delimited list of scopes granted for this token.


This structured JSON response ensures that the client can reliably extract the token, understand its lifetime, and confirm which permissions have been assigned.

##### Example


```
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:users write:logs"
  }
```

#### Access Token Use

Once issued, the access token must be included in the `Authorization` header of every request to protected endpoints, using the format `Authorization:` `Bearer <access_token>`.

##### Example


```
POST /v1/user-status
Host: api.sqr-group.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json
```