# Resource Owner Passsword Flow

## Overview

This flow is only available for use by NowInfinity Customers (signed SSLA agreements) accessing their own data.  Partners/integrations must use the Authorisation code flow. Customers are also encouraged to use the Authorisation code for increased security and better audit trail of which users made changes to data, as multiple users can authorise access to the data.

The **Resource Owner Password Credentials (ROPC)** grant is an OAuth 2.0 flow for **trusted clients** to obtain an access token by sending a user’s **username** and **password** directly to the authorisation server.

With the Resource Owner Password Flow, you can:

- Authenticate a user by sending their credentials to the authorisation server.
- Obtain an **access token** to call protected NowInfinity API endpoints.
- To receive a **refresh token** (via the `offline_access` scope) and an **ID token** (if supported).


**1. Client uses email and password:** Your integration makes a request to the token endpoint containing the username and password of the authorising user. This request identifies your integration and the scope of resources you wish to access.

**2. Return access_token and id_token:** NowInfinity returns a token response containing the Access token and, if requested an ID Token.

## Step 1: Requesting a Token

Before calling protected resources, request a access token from the token endpoint.

### Token Endpoints

- **Production:** `https://auth.nowinfinity.com.au/connect/token`
- **Tornado (sandbox):** `https://auth.nowinfinity-test.com.au/connect/token`


### 🧾 Authorisation Header (Basic)

Requests in this flow require **Basic** authentication using the `client_id` and `client_secret` issued for your Application/integration.

**Important:** The `Authorization` header is **case-sensitive**, including the word `Basic`.

**Build the header:**

1. Concatenate `client_id` and `client_secret` with a colon:
<client_id>:<client_secret>
2. Base64-encode that string, for example:
PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+
3. Add the result to the `Authorization` header:
Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+


```bash
Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+
```

## Supported Parameters

The following parameters are supported for token requests:

| Parameter | Required | Value | Description |
|  --- | --- | --- | --- |
| `grant_type` | True | `password` | The type of OAuth 2.0 grant being exchanged. Must be set to `password`. |
| `username` | True | `string` | The username of the Resource Owner. |
| `password` | True | `string` | The password of the Resource Owner. |
| `scope` | False | Space-delimited list of scopes | Describes the access being requested. |


## Example Token Request

An example token request, with white space added for readability:

```
curl -X POST https://auth.nowinfinity.com.au/connect/token \
  -H "Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "grant_type=password&username=SampleUser&password=Samplepwd&scope=api1"
```

## Token response

The token endpoint returns a response in JSON format.

For unsuccessful requests, the JSON object will contain two properties, error with an error value as described in Error codes, and error_description containing a more specific, human-readable error message.

For successful requests, the JSON object will contain the following properties:

| Parameter | Value | Description |
|  --- | --- | --- |
| `access_token` | An access token | This is the token that is used to access user resources via the NowInfinity API. |
| `token_type` | bearer | The type of access token. Currently, the NowInfinity API only supports Bearer tokens and this property will always have the value bearer. |
| `expires_in` | Integer | The number of seconds until the access token expires. I.e. 899. |
| `scope` | A space-delimited list of scope values | The actual scope of the access token. This may be different from what was requested in the scope parameter in the authorisation request. |


Examples of successful and unsuccessful token responses, with white space added for readability:

**Successful Response**

```
TBD
```

**Error Response**

```
TBD
```