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.
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 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
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.
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
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 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.Authorization: Bearer <access_token>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").
{
"access_token": "the_access_token_string",
"expires_in": 300,
"token_type": "Bearer"
"scope": "Public.Application.Read Public.Application.Write"
}
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
The access token request Postman collection is available publicly below: