Authentication

Last updated: 11 Jul 2024

Contents

  1. Overview
  2. Datacentres and Multi-tenancy
  3. Access Control
  4. Requesting Client Credentials
  5. URL Format
  6. Client Credentials Flow
  7. Postman Collection

Overview

PageUp APIs are secured using OAuth 2.0, which provides authentication and verification by way of an access token which must be included with each request.

Before you can generate an access token, you must obtain a client id and client secret from PageUp. These are referred to as 'client credentials' and can then be used to request an access token from the PageUp token endpoint. See the Requesting Client Credentials section for more information.


Datacentres and Multi-tenancy

PageUp provides cloud-based HR software to customers all around the globe. To ensure the best service to our customers, we utilise datacentres in multiple locations around the world to deliver our software.

Each datacentre is assigned an identifier and this is used to easily ensure requests can be sent directly to a specific datacentre.

Every PageUp customer is provisioned with their own tenant storage in one of our regional data centres, and as such, it is important to be aware of which datacentre houses the customer to which you're requesting access token. To make this easier, each PageUp customer has their own subdomain that is used when accessing the PageUp token endpoint. For example: mycompany.login.pageuppeople.com/connect/token...


Access Control

Access to PageUp APIs is restricted through the use of OAuth scopes. To ensure you can access the endpoints required for your integration, review the API documentation carefully and ensure all required scopes are provided when requesting client credentials. Once these scopes have been assigned to your client credentials, you may include them in your access token requests.

Should your requirements change, you can contact PageUp to change the scope attached to the client_id


Requesting Client Credentials

Your client_id and client_secret are used to identify you as a consumer of PageUp APIs, generate access tokens, and control what PageUp APIs you are allowed to access. To ensure the security of PageUp customer data, each client id can only be connected to one PageUp customer and one environment.

Each PageUp customer has two different environments (i.e. UAT and Production/LIVE) once the customer went LIVE.

Security best practice highly recommends that you store your client_secret encrypted at rest, particularly if you plan to commit it to a source control repository.

To obtain these credentials please speak with your company's HR Super User or PageUp representative. HR Super Users should refer to the Requesting API Credentials article in the knowledge portal for more information (or please feel free to contact your Customer Success Manager). Please note that different credentials for your UAT and Production environments.


URL Format

Root url:
https://<environment>.<dataCentreId>.pageuppeople.com/connect/token
Where
  environment = specify 'login' for production or 'loginuat' for development or testing
  dataCentreId = the data centre to connect to (e.g. dc2) 
Region dataCentreId
AUS dc2
UK / EMEA dc3
US dc4
SEA dc5

Please contact PageUp representative to find out the customer's data centre if not known.

Example - to request access token for production environment on dc2

https://login.dc2.pageuppeople.com/connect/token

Example - to request access token for UAT environment on dc3

https://loginuat.dc3.pageuppeople.com/connect/token

Client Credentials Flow

The client can request an access token using its client_id and client_secret credentials when requesting access to the protected resources. Access tokens issued by PageUp are only valid for 5 minutes (300 seconds).

+---------+                                  +---------------+
:         :                                  :               :
:         :>-- A - Client Authentication --->: Authorization :
: Client  :                                  :     Server    :
:         :<-- B ---- Access Token ---------<:               :
:         :                                  :               :
+---------+                                  +---------------+

Access Token Explained

  • access_token The value of the token.
  • expires_in The life time of the token in seconds.
  • token_type The type of the token. e.g. Bearer.
  • The header of a request to API may look like: Authorization: Bearer <access_token>

Client Authentication Request Template

Url: https://<PageUpTokenEndpoint>/connect/token
Method: POST
Header:
  Content-Type:application/x-www-form-urlencoded
Body:
  client_id:<clientId>
  client_secret:<clientSecret>
  grant_type:client_credentials
  scope:<accessControlScope>
Where
  clientId = a PageUp supplied ID used to identify the consumer
  clientSecret = a PageUp supplied secret key paired with the clientId
  accessControlScope = originates from a PageUp supplied list of allowed access scopes. 
  Depending on the operation, the consumer may opt to specify a single scope or multiple scopes (separated by a space i.e "scopeA scopeB scopeC").  

Example Client Authentication Response

{
    "access_token": "the_access_token_string",
    "expires_in": 300,
    "token_type": "Bearer"
    "scope": "Public.Application.Read Public.Application.Write"
}

Example Access Token Usage

Once an access token has been created, it is valid for n seconds as defined by the "expires_in" value. It is highly recommended that the token be reused until near expiry to improve performance. To access to the relevant endpoint, add a header to the requests (below)

Header:
  Authorization:Bearer the_access_token_string

Postman Collection

The access token request Postman collection is available publicly below:

https://postman.com/puptechsolution/workspace/pageup-public-workspace/documentation/421061-72aab701-b61c-4a4d-97c6-3d1d33228c62