# Resource owner password credentials grant

# Introduction

Resource owner password credentials grant is suitable when the client is a regular Pagero Online customer who only wants to access the Pagero Online REST API for own purposes.

It is described in detail in section 4.3 of the OAuth2 specification.

It consists of the following steps:

The client makes a request to obtain an access_token and a referesh_token, using the client credentials and the credentials of a Pagero Online user.
The access_token can be used to make API requests.
When the access_token expires, the refresh_token can be used to obtain a new access_token. The refresh_token never expires and it is important that this is kept safe by the client. A refresh token can however 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.

The different steps are described in detail below.

# Obtaining an access token

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

https://auth.pageroonline.com/oauth2/token

Required query parameters:

Parameter	Description
`grant_type`	Should be `password`.
`username`	The username of a Pagero Online user to authorize.
`password`	The password of a Pagero Online user to authorize.

Required headers:

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

# Example

Example with curl
curl https://auth.pageroonline.com/oauth2/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:

{
  "scope": "all",
  "access_token": "7367e3e0-eb0a-4abe-95ce-83363c27eaa2",
  "token_type": "bearer",
  "expires_in": 300,
  "refresh_token": "afee9ede-1394-40c1-a917-f0fb5b775899"
 }

# 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

Example with curl
curl https://api.pageroonline.com/someresource \
  -H 'Authorization: Bearer 7367e3e0-eb0a-4abe-95ce-83363c27eaa2'

# Using a refresh token to obtain an access token

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

https://auth.pageroonline.com/oauth2/token

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 query parameters:

Parameter	Description
`grant_type`	Should be `refresh_token`.
`refresh_token`	The refresh token.

Required headers:

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

# Example

Example with curl
curl https://auth.pageroonline.com/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=afee9ede-1394-40c1-a917-f0fb5b775899 \
  --user 'client-id:client-secret'