Paylocity API access and credential provisioning guide

Key takeaways

Keep these distinctions in mind when requesting and testing access:

• Paylocity issues initial OAuth credentials and sandbox access after reviewing and approving the access request.
• For a customer-specific build, the customer's company administrator submits the request through the customer's Paylocity account executive.
• Token issuance and authorized data access are separate checks, so a successful token request does not establish access to every company, endpoint, or operation.
• Your token endpoint and request parameters must match the documented API family and environment, without transferring WebLink settings to another family.
• Sandbox success is not production approval, which requires Paylocity review against its integration requirements.
• Client-secret renewal is separate from access-token replacement, with its own expiration, contact, and maintenance route.

You cannot sign up for Paylocity API credentials. Paylocity issues a client ID, a secret and a sandbox only after it reviews and approves an access request, and for most B2B vendors that request needs a Paylocity customer willing to stand behind it.

The request defines the access you will get. Your authentication setup has to match what was issued, and production still needs a separate review. This guide covers the request route, authentication, access validation, production readiness and secret maintenance, for engineering leads connecting an HR, payroll or benefits product to a customer's Paylocity account.

Choose the access request route

For a customer-specific integration, the Paylocity customer's company administrator submits the project request through the customer's account executive. Prospective technology partners and customers using an existing partner integration follow different routes.

Paylocity's Integration Requirements and Integrations FAQ distinguish these situations:

Sandbox access has its own gate. Paylocity's Getting Started guide says you must be an existing Paylocity customer, or have at least one existing Paylocity customer willing to join early adoption testing, advocate for the access level your integration needs, and sign off on access change requests during development and testing. Its Integrations FAQ adds the partnership route: a signed Marketplace Partner Agreement and agreement to commercial terms.

For a vendor without a partnership, that makes the first customer a prerequisite, not a launch target. Line up that customer and their company administrator before you write the request.

Assemble the request packet

Paylocity documents the business case, primary business and technical contacts, and written participation consent as request contents. Add a data-and-operations scope record for engineering clarity; that addition is a recommended acceptance detail, not a claimed universal Paylocity form field.

Include these details in your request packet:

• A business case that explains what the integration will do and why the customer needs it.
• Primary business and technical contacts who are responsible for decisions and implementation.
• Written participation consent that records the customer's agreement to participate.
• A scope record that names the requested data, endpoints, and intended read or write operations.

For API and integration pricing, Paylocity directs customers to their account executive. Confirm applicable charges there rather than assuming that access is free or that a particular fee schedule applies.

Record what the issued access authorizes

Record authorization separately from token-generation status. Paylocity's Integration Requirements checks credential authorization for requested endpoints independently of token generation, and its testing requirements include customer signoff on the required access levels to company data.

Suppose your request covers a sandbox read from one company. Keep that expectation attached to the issued credentials. Receiving a token must not silently expand the acceptance criterion to every company or to write operations.

Use this checklist for your own access acceptance record. It is not a representation of a Paylocity portal screen:

• Record the intended company or company set and the assigned companyId, where applicable.
• Record whether the issued access is for sandbox or production.
• Record the documented API family associated with the credentials.
• Record the requested endpoints and read or write operations.
• Record confirmation of endpoint authorization and the required customer signoff on company-data access.
• Record the credential owner and technical contact.
• Record token-generation test status separately from data-access test results.

This record helps you specify and check the access you need; it does not itself restrict granted token privileges. For least privilege, the IETF's RFC 9700, published in January 2025, recommends restricting access-token privileges to required resources and actions.

The credential handoff should tell you what to test as well as which secret to load.

Match authentication to the API family and environment

Choose the token endpoint by documented API family and environment. Paylocity's general Authentication reference and WebLink Authentication reference publish different endpoints and different sample parameters.

Both published token requests are form-encoded and include client_id, client_secret, and grant_type=client_credentials. Check the difference in scope:

The general-API sample establishes what that published example sends. It does not establish a universal rule that every API labeled NextGen requires no scope, nor does it prohibit scope in every configuration. Confirm the requirements for the API family associated with your issued access; do not fill that uncertainty with WebLink's scope or endpoints.

For calls to the API, Paylocity requires TLS 1.2. Send the token obtained from Paylocity's identity provider in the Authorization header using the bearer-token mechanism:

Authorization: Bearer 

A complete token request against the general platform's testing endpoint, and its response:

curl -X POST "https://dc1demogwext.paylocity.com/public/security/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=" \
  --data-urlencode "client_secret=" \
  --data-urlencode "grant_type=client_credentials"

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

For WebLink, change the host to https://dc1demogw.paylocity.com/IdentityServer/connect/token and add scope=WebLinkAPI. How to cache and isolate these tokens in a running service is covered in Paylocity API architecture: authentication and data access.

These configuration values let you attempt authentication. They do not establish that the credentials authorize the company, resource, operation, or environment you intend to use.

Validate usable access and investigate failures

A successful token request establishes token issuance, not successful access to your target company data. Verify usable access with a separate, non-destructive read against the company and resource in your acceptance record.

Run the checks in this order:

1. Test token issuance: send the documented form-encoded request to the token endpoint for the issued API family and environment. Record whether token generation succeeds.
2. Test an authorized read: use the issued bearer token for a non-destructive read against the previously scoped company and resource.
3. Compare the result: check the returned data against the expected company and authorized access level. In the single-company sandbox example, success means receiving the expected authorized data from that company, not merely receiving a token.

For response interpretation, the IETF's RFC 9110, published in June 2022, defines 401 as missing valid authentication credentials for the target resource. A 403 means the request was understood but refused, potentially for reasons beyond credentials. Neither status supplies a complete Paylocity-specific diagnosis.

Use this diagnostic record during investigation. The checks and escalation owners below are recommendations, not an exhaustive Paylocity error-code mapping.

Replace access tokens before expiration

Paylocity's Authentication reference gives bearer tokens a lifetime of 3,600 seconds. An expired token produces a 401 response; obtain a replacement through another token-endpoint request before expiration.

That replaces the access token. It does not renew the client secret or establish production approval.

Complete the production-readiness checks

A working sandbox connection is not production approval. Paylocity requires sandbox integration testing before the integration is submitted for review, and its Integrations FAQ says go-live approval requires review against the activities and deliverables in its Integration Requirements guide.

Use these checkpoints to organize the remaining work:

1. Assign testing responsibilities: name the integration owner who will guide participants through required actions, mapping, and testing requirements. Paylocity assigns that coordination responsibility to the integration owner.
2. Complete sandbox testing: finish the required tests and retain completion evidence and customer signoff. Keep successful token generation distinct from evidence of authorized company-data access.
3. Submit for Paylocity review: present the integration for review against Paylocity's required activities and deliverables. Completing your checklist does not guarantee approval.
4. Confirm production access: record the issued production environment and authorization, then validate the intended access there. Do not treat editing a sandbox URL as production authorization.

Your readiness record should show both technical results and the provider's approval outcome. If either is missing, the launch check remains open.

Maintain client secrets through expiration and replacement

Client-secret maintenance is a separate lifecycle from access-token replacement. Paylocity requires client secrets to rotate every 365 days, with expiration notifications sent to the identified contact 10 and 5 days before expiration.

Paylocity's Authentication reference distinguishes supported maintenance routes: credentials managed through the Developer Portal follow its renewal or rotation route; APIs not supported there require the assigned support representative to perform rotation. Confirm which route applies rather than assuming that every credential can be renewed through the portal.

Paylocity's Create New Client Secret reference has specific prerequisites: a Paylocity-issued client ID and a code supplied in the WebLink API credential-expiration notification. That endpoint is not an alternative route for obtaining initial API access.

Keep a lifecycle checklist alongside the access record:

• Assign a renewal owner and a monitored contact for expiration notices.
• Record the client-secret expiration separately from access-token expiration.
• Confirm the supported renewal route and the party responsible for executing it.
• Deploy the replacement secret and verify token generation and the expected authorized read.
• Store credentials in dedicated secret management and exclude secret values from support artifacts.

OWASP's 2025 NHI2: Secret Leakage guidance identifies repositories, logs, plaintext configuration, and public chat as places where application secrets can leak. It recommends dedicated secret management and preventing hardcoded secrets.

When troubleshooting, share the configuration choice, observed status, and redacted evidence, not the client secret or bearer token. The person who can resolve the failure does not need an unredacted credential in a ticket or chat message.

What changes when a unified API holds the connection

Request ownership, authorized access, testing and renewal all need an owner whichever way you build. A unified API moves some of that work. It does not move Paylocity's approval process.

Bindbee has a live Paylocity connector, over the API and as an SFTP file feed. With it, your application authenticates to Bindbee rather than to Paylocity: a Bindbee API key identifies your organization, and an X-Connector-Token identifies one customer's connection. Passthrough calls to Paylocity endpoints use the credentials Bindbee already holds for that connection, so Paylocity secrets stay out of your services, logs and tickets.

Paylocity's request, approval and go-live review apply in both columns. With Bindbee, each employer takes the customer-specific route from the table at the top of this guide. Bindbee's Paylocity setup guide walks the employer's administrator through Paylocity's Web Services Access Request Form, sent to service@paylocity.com, and Paylocity may charge for that setup. The administrator then enters the company ID, client ID and client secret into Bindbee's Magic Link.

The 365-day secret rotation stays with the employer too. When the secret changes, the connector moves to RELINK_NEEDED, the administrator relinks it with the new values, and the connector token your application stores stays the same.

Bindbee's Paylocity integration page lists the models the connector reads. To map your access record against it, book a technical review.

Frequently asked questions

How do I get Paylocity API credentials?

Submit an access request. For a customer-specific build, the customer's company administrator requests it through their Paylocity account executive; prospective partners start with the Marketplace Partner Intake Form. Paylocity issues the client ID, secret and sandbox after approval.

Can I get a Paylocity sandbox without being a customer?

Only with a customer or a partnership behind you. Paylocity requires you to be an existing customer, have at least one customer willing to join early adoption testing, or sign a Marketplace Partner Agreement.

Does Paylocity charge for API access?

It can. Paylocity directs customers to their account executive for API and integration pricing, so confirm any charges there rather than assuming access is free.

How often do Paylocity client secrets expire?

Every 365 days. Paylocity notifies the identified contact 10 and 5 days before expiry. Renewal runs through the Developer Portal for supported credentials, or through your assigned support representative for APIs the portal does not cover.

How long does a Paylocity access token last?

3,600 seconds. There is no refresh token, so request a new one from the same token endpoint before the current one expires. Replacing an access token does not renew the client secret.