Transport Layer Security (TLS)

Transport Layer Security (TLS) is a security protocol widely used for encrypting communications between web applications and servers. An HTTPS transfer or API call happens over a connection secured by TLS.

You must use TLS 1.2 when calling our APIs.

To check if TLS 1.2 is supported in your HTTPS library, review the library documentation or configuration settings for mention of TLS Versions.

Authentication & Authorization

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

❗️

Weblink API

Our Weblink API uses different servers and syntax to obtain bearer tokens.
Please review that documentation here Weblink API Auth

Sample request to the /token endpoint:

curl --location 'https://dc1prodgwext.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'

📘

Auth endpoints per environment

Testing - https://dc1demogwext.paylocity.com/public/security/v1/token

Production - https://dc1prodgwext.paylocity.com/public/security/v1/token

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, as seen in the sample HTTP header.

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.

🚧

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.