abstract swish line in gradient colouring from pink to blue on a dark blue background

People First API

Authentication

People First APIs require authentication in order for an application to access them and make API calls. An API client authenticates itself with People First by providing a valid token within the Authorization header of each HTTP request (see: HTTP/1.1 Authentication for further details of the Authorization header).

The following types of token are supported within the Authorization header:

 

People First Access Token (recommended)

Access Tokens are generated in the admin area of People First by a user with a system administrator role. For details of how to do this, please see the REST API Integration section.

Depending upon the API being consumed, access tokens should be supplied within the HTTP Authorization header using one of two HTTP authentication schemes:

Bearer Authentication (recommended)

When using the Bearer Authentication scheme the header will be in the form:

Authorization: Bearer ACCESS_TOKEN


Where:

  • ACCESS_TOKEN is the access token supplied by your System Administrator.

Basic Authentication

When using the Basic Authentication scheme the header will be in the form:

Authorization: Basic USERNAME:ACCESS_TOKEN


Where:

  • USERNAME:ACCESS_TOKEN is base 64 encoded.

  • USERNAME will be ignored, so can be omitted. However, the : must always be included.

  • ACCESS_TOKEN is the access token supplied by your System Administrator.

     

OpenID Connect ID Token

An OpenID Connect (OIDC) ID token represents the identity of a People First User. They allow an application to call the People First APIs as though they were that user, inheriting whatever roles and permissions have been assigned to that user. They are only valid for a limited timespan before they need to be refreshed. Typically, ID tokens are used for one-time ad-hoc requests for data.

ID tokens are obtained from a tenant's registered identity provider and take the form of a JSON Web Token (JWT) signed by that provider. They can be requested from an identity provider by various methods, as outlined in the OpenID specifications. Usually, a JWT ID token will be captured via a browser-based flow with an actual user performing authentication.

JWTs should be supplied within the HTTP Authorization header using the HTTP Bearer authentication scheme. A typical API request is shown below:

GET /api/v1/profile HTTP/1.1
Host: eu.peoplefirst.com
Authorization: Bearer ID_TOKEN


Where:

  • ID_TOKEN is the ID token obtained from the tenant's registered identity provider.
     

API Authorisation

The authorisation of API requests is governed by the assignment of one or more roles to either the application itself (if an OAuth2 client credentials flow is being used), or to the People First generated access token that the application supplies. If using an ID token then authorisation will be governed by the roles and permissions assigned to the user who granted that ID token.

The following roles are currently available:

  • Custom Cards Integration  
    provides access to the Custom Card OData and import endpoints
     
  • HRM Integration  
    provides access to HRM import endpoints and several HRM resource endpoints (e.g. People, Unit, Job, and Occupancy related)
     
  • IAM Integration 
    provides access to selected HRM Occupancy resource endpoints, and IAM resource and import endpoints
     
  • Learning Integration 
    provides access to the Learning OData endpoints
     
  • Recognitions Integration 
    provides access to the Recognitions OData endpoints
     
  • Recruitment Integration 
    provides access to the Recruitment OData endpoints
     
  • Socialfeed Integration 
    provides access to the Social Feed OData endpoints
     
  • Talent Integration 
    provides access to the Talent OData and selected resource endpoints
     
  • Workforce Management Integration 
    provides access to selected Time and Attendance resource and import endpoints
     
  • System Integration 
    provides access to the majority of People First API endpoints, including the Event Stream API
     
  • Payment file integration 
    provides access to payment files from payroll
     
  • Pension integration 
    provides access to the pension export endpoint
     
  • Costing integration 
    provides access to the costing endpoint
     
  • Onboarding integration 
    provides access to onboarding OData end points
     
  • Custom Cards Imports 
    provides access to Custom Card import and export endpoints
     
  • HRM Imports 
    provides access to the HRM import endpoints
     
  • Talent Data Imports 
    provides access to the Talent import endpoints
     
  • Payroll Imports 
    provides access to the Payroll import endpoints
     
  • TA Imports 
    provides access to the Time and Attendance import endpoints

  • IAM Imports 
    provides access to Identity and Access management import endpoints


     
     

Looking for something specific?