# Resource owner password credentials flow

> [!IMPORTANT]
> It is critical to securely manage sensitive credentials, including the username, password, client ID, and client secret.
> Exposure of these credentials can lead to unauthorized access and security breaches.
> **Never hardcode the credentials in your application code, configuration files, or version control systems.**
> Failing to follow these security best practices can compromise system integrity and user data. We strongly recommend implementing proper secret management strategies.
>

## Introduction

If the external system or application does not require user interaction for authentication and can securely store the user's username and password, the Resource Owner Password Credentials (ROPC) Flow can be used to obtain an access token.

In this flow, the user's credentials are sent directly to the authorization server, which then issues an access token and a refresh token.

---

## Obtaining an access token

To obtain a new `access_token`, the following URL should be used:

- <https://sso.pageroonline.com/oauth/v2/oauth-token>

Request Method: **POST**

Required parameters in `application/x-www-form-urlencoded`:

Parameter | Description
------------ | -------------
`grant_type` | Must be `password`.
`username` | The username of a Pagero Online user to authorize.
`password` | The password of a Pagero Online user to authorize.
`client_id`* | The client ID.
`client_secret`* | The client secret.

Required headers (if not `client_id` and `client_secret` provided in the body):

Header | Description
------------ | -------------
`Authorization` | Authorization header for basic authorization, where the user should be the client id and password should be the client secret.

#### Example with header option

```text Example with curl
curl https://sso.pageroonline.com/oauth/v2/oauth-token \
  -d 'grant_type=password' \
  -d 'username=<username>' \
  -d 'password=<password>' \
  --user 'client_id:client_secret'
```

The response will contain a JSON body that looks like this:

```json
{
  "token_type": "bearer",
  "access_token": "eyJraWQiOiIxNTUzNzgyMDQxIiwieDV0IjoiYldvWF...",
  "refresh_token": "_1XBPWQQ_d88969ce-25dc-40af-a558-fc647632d610",
  "scope": "",
  "expires_in": 600
}
```

> [!NOTE]
> The `access_token` value is redacted for brevity. The actual JWT that is issued will be longer.

> [!IMPORTANT]
> The refresh token is issued with a **rolling lifetime of three years**,
> allowing it to generate new access tokens continuously within this period.
> After three years, user authentication will be required to obtain a new refresh token.
>

---

## Making an API request using an access token

When making an API request, the `access_token` should be provided in an Authentication header as a bearer token.

#### Example

```text Example with curl
curl https://api.pageroonline.com/someresource \
  -H 'Authorization: Bearer eyJraWQiOiIxNTUzNzgyMDQxIiwieDV0IjoiYldvWF...'
```