Auth

Overview

The Workforce Planning API endpoints allow two methods of authentication: Oauth 2.0 and Basic Authentication. Although terminology like client_id and client_secret are the same, they are not interchangeable between Basic and OAuth. These concepts should not be conflated when implementing your preferred authentication method. Both are outlined in more detail below.

Additionally, while your connection to the Workforce Planning API will be encrypted via TLS, we encourage clients to review the security environment around their implementation to confirm they are comfortable with who internally has access to these systems, what other systems have access to the same network and what type of information you will be transmitting in this manner to the Workforce Planning API.

OAuth 2.0 Authentication

We follow the industry standard spec for OAuth 2.0 outlined here and issue expiring JSON Web Tokens to provide integrators restricted access to your APIs.

To get started you will need to go to the Company Settings -> Oauth Apps area of the Workforce Planning tool UI and create an Oauth Application. This newly created application will have a client_idand client_secret assigned to it. Please save these values somewhere secure. You will not have another chance to see the client_secret again after it is created.

Once you have your client_id and client_secret pair, you can use it to generate an access token against the OAuth Token Endpoint.

// Example token request using Javascript

// Note: Your API base path may look different. Please check the UI where you created the Oauth App for this value
const url = 'api-app.laborchart.com/v2/oauth/token'

const response = await fetch(url, {
  method: "POST",
  body: JSON.stringify({
    client_id: '<CLIENT_ID>', // The client_id of your OAuth Application
    client_secret: '<CLIENT_SECRET>', // The client_secret of your OAuth Application
    company_id: '1234-abcd-5678-efgh', // The ID of the company where the Oauth Application was created
    email: '[email protected]', // The email of the user that the token will be associated to. NOTE: They must be a valid user belonging to the same company
  }),
});

// If done correctly, response.json() will return an access token
console.log('My access token is: ', response.json())

To authenticate your API requests using this token, add it in your request's Authorization header value like so:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX...

This new access token will be valid for two hours before it expires and a new one must be issued by calling the oauth/token endpoint again.

Note: If the OAuth Application is marked inactive, any attempts to issue new access tokens will fail. Previously issued tokens using the app before it was inactivated will be valid until they expire.

Please reach out via email to [email protected] if you have any questions.

Basic Authentication

For the Basic Auth protocol, your integration lead will be provided with:

Base API URL
Company ID
Client ID ( username )
Client Secret ( password )

The Basic Auth protocol is a well-documented subject and there are many language-specific frameworks with the facility built into them but the quick overview is your username and password should be formatted as below:

username:password

Then base64 encode the above string and place it in your request'sAuthorization header value like so:

Basic dXNlcm5hbWU6c2VjcmV0Cg==

Note: Although all data you are sending to our API (which includes this auth header) is encrypted and thus safe, you should be aware that base64 encoding is not encryption and can be reversed. Due to this, you need to treat the base64 encoded version of your API credentials as if they were visible text when storing them on your personal machine, with your integration servers or 3rd party tools.

_In order to gain access to your company's Workforce Planning API, please reach out via email to [email protected]