# Using a refresh token to obtain an access token

## Introduction

A refresh token is a credential used to obtain a new access token when the current one expires, without requiring the user to log in again.

Once the access token expires, the refresh token is sent to the authorization server to request a new access token. This process reduces the need for frequent re-authentication while maintaining secure access to resources.

---

## Obtaining a refresh token

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

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

Request method: **POST**

Please note that a refresh token can only be used once.

When using a refresh token to get hold of an access token, a new refresh token will also be provided in the response.

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

Parameter | Description
------------ | -------------
`grant_type` | Should be `refresh_token`.
`refresh_token` | The refresh token.
`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`.

Response Structure:

| Parameter    | Description                                      |
|--------------|--------------------------------------------|
| `access_token` | A freshly generated JSON Web Token (JWT) |
| `refresh_token`| A freshly generated refresh token          |
| `expires_in`   | Time in seconds until expiration           |
| `scope`        | A string with space-separated values       |
| `token_type`   | Bearer or another type of token            |

#### Example with header option

```text Example with curl
curl https://sso.pageroonline.com/oauth/v2/oauth-token \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=_1XBPWQQ_e61b091b-9139-4268-a7c7-765d2d418d52' \
  --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_e61b091b-9139-4268-a7c7-765d2d418d52",
  "scope": "",
  "claims": "publicid",
  "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.
>