Powered by

# Authorization code

# Introduction

Authorization Code Grant is suitable when the client is an integrating system which will be making API calls on behalf of their users, who are also Pagero Online users.

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

It consists of the following steps:

  1. The client (the integrating system) directs the end user to the Pagero login page.
  2. Upon successful login, an authorization_code will be sent back to the client.
  3. The authorization_code is used to obtain an access_token and a refresh_token.
  4. The access_token can be used to make API requests.
  5. When the access_token expires, the refresh_token can be used to obtain a new access_token. A refresh token can only be used once and when using a refresh token to get hold of an access token, a new refresh token will also be provided in the response. Refresh tokens expire after 1 year.

The different steps are described in detail below.

# Direct the end user to the Pagero Online login page

The URL of the Pagero Login page is:

Required query parameters:

Parameter Description
response_type Should be set to code to generate an authorization_code.
redirect_uri The client URI where the user will be redirected after successfully providing credentials. This URI must be the one that was agreed upon when the client was registered.
client_id The client id.

# Example

# Authorization code is sent back to the client

Upon successful login, the authorization_code is posted back as a query parameter to the url defined in the redirect_uri query parameter:

# Example

  • https://urltoclient:4443/?code=247ee7f7-a456-4873-bd12-1804aac9fc6b

# Using the authorization code to obtain access token and refresh token

Using the authorization_code, it’s now possible to obtain an access_token and a refresh_token.

The URL for doing so is:

Required query parameters:

Parameter Description
grant_type Should be authorization_code.
code The authorization code.
redirect_uri Must be identical to the redirected uri that was provided in the first step above.

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=authorization_code \
  -d code=247ee7f7-a456-4873-bd12-1804aac9fc6b \
  -d redirect_uri=https://urltoclient:4443 \
  --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 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:

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'

© Copyright 2024 Pagero. All rights reserved.