TriNet APIs support server-to-server interactions such us integrations between TriNet and other applications. In this scenario, an end-user application is not ideal as most of those integrations occur in the background and user authentication capabilities are limited. For this type of application you will need a service account that belongs to your application rather than individual user. We recommend you use the service account for the following reasons:

  • Security: B2B applications require passing a password as part of the authorization call. Using actual user credentials for this password means that the user would have to give out his\her TriNet password. This is a security concern and may create an additional administration task to keep the user password in sync.
  • Chain of custody: TriNet  tracks the changes made by each individual user, making it important to keep API interactions and actual user interactions separate. If you use actual user credentials, it will not be possible for the system to determine whether a change was made by the actual user or the API.
  • Application stability: Tying the API to an actual user carries additional stability concerns. For example, if the user leaves the company and the user’s account is deactivated/limited in TriNet, the application will no longer have the required access and the user ID will need to be updated.

These applications follow a basic flow when accessing TriNet:

Create a Service Account

Create a "Trusted Advisor" user in TriNet. This will be the service account for your application.

Obtain an Access Token

Before an application can obtain data using TriNet APIs, it has to obtain an access token from the authorization server. One access token can grant access to multiple APIs.

B2B applications will use the OAuth 2.0 Password Grant approach to acquire access token from the TriNet authorization server. In that flow you will make a call (POST) to following URL: https://gateway.hrpassport.com/trinetAuth/services/v1.0/authorization/oauth2/access-token

Sample request payload:

{
  "clientId": "clientID",
  "clientSecret": "clientSecret",
  "username": "employeeID",
  "password": "password"
}

When the call is successful, the access and refresh tokens are granted.

Sample response:

{
  "scope": "client_id cn companyid emplid mail personid uid",
  "expires_in": 59,
  "token_type": "Bearer",
  "refresh_token": "bd27fb0b-5c7a-43ed-b4f8-bdc8af809a9b",
  "access_token": "657e4ddb-b0ec-412a-84f7-f78246d91c39"
}

 

Use the Access Token in All API Calls

After the application obtains an access token, it sends it in HTTP authorization header in "Bearer {access_token}" format.
Sample cURL command to retrieve all employee details with authorization header:
 
curl -v -H "authorization: Bearer {access_token}" -X GET "https://api.trinet.com/v1/company/{companyId}/employees"

Access tokens are valid only for a limited amount of time, which is specified in the "expires_in" field of the response. We recommend you write your application to anticipate that a token may stop working for one of the following reasons:

  • The token expired (see Refresh the Access Token below for more information).
  • The user's access was revoked access and you no longer have the necessary access.

Refresh the Access Token

When an access token expires, you can use a refresh token to obtain a new one. To obtain a new access token, call (POST) to the following URL: https://gateway.hrpassport.com/trinetAuth/services/v1.0/authorization/oauth2/refresh-token?client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}

You will be granted a new access token and refresh token to use. Refresh tokens are valid for 8 days. If the refresh token expires, you will need to authenticate again.