Authentication

Paylocity APIs utilize the Client Credentials flow from OAuth2 for authentication. This means that every call to a Paylocity API will include an HTTP Header named Authorization with a value that includes a short-lived bearer token obtained from the Paylocity Identity Provider (IDP).

Sample HTTP Header:

Authorization: Bearer TOKEN_GOES_HERE

To obtain a bearer token, consumers must first have their a client_id and secret, received after completing steps 1-3 from Getting Started. These credentials will be used when interacting with the Paylocity IDP by invoking the IDP’s /token endpoint to obtain the token.

• client_id: this is the client_id assigned to the registered application in the developer portal
• secret: this is the secret assigned to the registered application in the developer portal.
• grant_type: the value provided here must be client_credentials

🚧

Secure your API Credentials!

Your credentials carry many privileges, so be sure to keep them secure! Do not share your credentials in unsecured emails or publicly accessible areas such as GitHub, client-side code...etc.

Secrets are required to be rotated once every 365 days. An email notification of your secret expiring is sent to the identified contact 10 days and 5 days prior to the expiration.

Sample request to the /token endpoint:

curl --location 'https://gwext.paylocity.com/public/security/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=dfff6fdfb9a145d59389542285dfa505' \
--data-urlencode 'client_secret=...' \
--data-urlencode 'grant_type=client_credentials'

Sample response from the /token endpoint:

{ 
  "access_token": "....", 
  "token_type": "Bearer", 
  "expires_in": 3600 
} 

The value in the access_token field is the value that is used in the TOKEN_GOES_HERE placeholder above.

It is important to note that the bearer token is short-lived and will expire after 1 hour (3600 seconds). The use of an expired token will result in a failed response (status code 401) from an API. Before the token expires, consumers should obtain a new bearer token by sending another request to the /token endpoint.