ADP Workforce Now API architecture, authentication, and data access

Key takeaways

• The ADP Workforce Now API is a REST/JSON integration covering the full employee life cycle: HR, time and labor, payroll, recruiting, and benefits.
• Server-to-server calls authenticate with OAuth 2.0 client credentials combined with mutual TLS, so every call also presents an X.509 certificate.
• Access tokens expire in 60 minutes (3,600 seconds), and a valid token still doesn't guarantee data access.
• Access is separately gated by the caller's role, its data entitlement, and the canonical URI registered in the Consumer Application Registry.
• Rate limits are tier-specific: API Central projects cap under 120 requests per 60 seconds, Marketplace partner projects under 300.
• Marketplace partners manage up to five separate credential sets to retrieve and maintain a client's OAuth credentials.

Ask a team what it takes to integrate with ADP Workforce Now, and most answer in one sentence: get an OAuth token, call the endpoint. That sentence describes maybe half the system.

Get the certificate wrong and every call fails before it starts. Get the entitlement wrong and every call succeeds, and returns nothing you need.

ADP Workforce Now's API spans the full employee life cycle, HR, time and labor, payroll, recruiting, and benefits, all through REST/JSON calls. Server-to-server calls authenticate with an OAuth 2.0 access token that expires in 60 minutes (3,600 seconds). The token is only the first check: ADP separately checks the caller's role, its data entitlement, and the canonical URI registered for the calling application before a single field comes back, and a request with a perfectly valid token can still return a 403 for exactly this reason.

This guide walks the architecture in the order a build needs it: what the API covers, how the OAuth-plus-mTLS handshake works, what gates access once you're authenticated, the operational limits any build has to size around, and how Marketplace partners manage credentials across many clients at once.

What the ADP Workforce Now API actually is

ADP Workforce Now exposes its data through a REST/JSON interface. According to ADP's documentation, that interface spans the full employee life cycle:

• HR
• Time and labor
• Payroll
• Recruiting
• Benefits

Three kinds of caller can reach it: ADP clients working through API Central, Marketplace partners building products for many ADP customers at once, and third-party integrators connecting on a client's behalf. Which route applies to you decides how much of the rest of this guide is your problem, since the partner credential model in a later section only exists for the second group.

Workforce Now is one product in ADP's HCM lineup, alongside RUN, Vantage HCM, Lyric, DECIDIUM, and iHCM. The architecture, endpoints, and limits described here are Workforce Now's; the sibling products differ enough that none of this transfers by assumption.

For a deeper walkthrough of this API's endpoints and objects, see our detailed guide to the ADP API. If you're on the client side and still need to buy access, our guide to ADP API Central pricing and setup covers who pays and how provisioning works.

None of those three access routes returns data until you clear the authentication layer ADP puts in front of every call, and that layer is stricter than a single OAuth token.

How authentication works: OAuth 2.0 client credentials plus mutual TLS

Server-to-server calls to Workforce Now authenticate with OAuth 2.0 client credentials combined with mutual TLS: the caller presents both an OAuth token and an X.509 client certificate on the same connection. ADP requires that certificate on every call to accounts.adp.com and api.adp.com. It is the same pattern IETF RFC 8705 standardizes for mutual-TLS client authentication and certificate-bound tokens. Neither credential substitutes for the other; a valid token over an unauthenticated connection, or a valid certificate with no token, both fail.

Getting a token

The caller base-64 encodes the client ID and secret and sends them via HTTP Basic authentication to ADP's token endpoint at accounts.adp.com/auth/oauth/v2/token. If the credentials don't validate, ADP returns an HTTP 401, meaning the token request itself failed, before any question of what the token can access. A successful request returns an access token good for 60 minutes (3,600 seconds), after which you request a new one. The client-credentials grant doesn't issue a refresh token.

curl -X POST "https://accounts.adp.com/auth/oauth/v2/token" \
  --cert adp-client.pem --key adp-client.key \
  -u "$ADP_CLIENT_ID:$ADP_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

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

Presenting the token

Every subsequent request carries the token in an Authorization: Bearer header, with a space between "Bearer" and the token value. That's the presentation format IETF RFC 6750 specifies for bearer tokens generally. ADP adds its own handling rules: never pass a token in cookies or URL parameters, reuse it for every call inside its 60-minute window instead of requesting a new one per call, and discard it when your job finishes. A token in a query string is a token in your server logs, your proxy logs, and your browser history.

curl "https://api.adp.com/hr/v2/workers?\$top=100&\$skip=0" \
  --cert adp-client.pem --key adp-client.key \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The end-user login flow is different

If your product also needs a human to log into their own ADP account, that's a separate flow from the data-connector auth above. ADP layers OpenID Connect on top of OAuth 2.0 for this case, following the authorization-code flow OpenID Connect Core 1.0 defines: an authorization endpoint returns a code, alphanumeric and 25 to 128 characters, and a token endpoint exchanges it for tokens. ADP's endpoints for this flow sit at accounts.adp.com/auth/oauth/v2/authorize and /token, with userinfo at api.adp.com/core/v1/userinfo and logout at accounts.adp.com/auth/oauth/v2/logout.

The client-credentials grant your data connector uses, by contrast, has no login screen and no user in the loop; it's defined once, plainly, in our guide to choosing a unified HR and payroll API, where the OAuth-delegated-access-versus-login distinction gets its full treatment. Here, the short version is enough: your integration authenticates as itself, not as any particular user.

Clearing this layer gets you a valid, authenticated connection. It does not get you data, and the gap between those two things is where most ADP integration plans go wrong.

Why a valid token still isn't access

A 403 with a token that authenticated just fine usually means ADP is working as designed. Its error semantics say exactly that: a 403 means the token is valid but the caller isn't authorized for the resource requested, which is a different failure than the 401 you'd get from bad credentials. Authentication proves who is calling; authorization decides what they're allowed to see, and ADP answers them separately.

Three things gate access once you're authenticated:

• The API user's role and permissions within the customer's Workforce Now tenant
• Data entitlement, which determines which JSON fields are visible based on the consumer's rights and population limits
• The canonical URI registered for your application in the Consumer Application Registry

This shows up concretely in how individual endpoints behave. A call to GET /hr/v2/workers returns only the workers the requester is authorized to view, at most 100 per page with $top, and the Workers API supports OData $top, $skip, and $filter, so you can page through them or filter by a field like original hire date. The Pay Statements API works differently: it offers GET-all, GET-by-ID, and image retrieval as PDF or ZIP, with no OData support at all, so a filtering pattern built for Workers has nothing to attach to on Pay Statements.

That asymmetry is worth internalizing before you design a data model around one endpoint's shape and assume the rest match it. Our guide to using an employee data API covers the broader pattern of how HR systems expose and scope fields differently by object, which is the same problem ADP's per-endpoint inconsistency is one instance of.

Getting past the entitlement and role checks tells you what you're allowed to ask for. It says nothing yet about how much you can ask for, or how often, which is where the next set of limits comes in.

Operational limits and error codes

The table below consolidates every limit and error condition ADP documents for Workforce Now, organized by what it constrains: token lifetime, request volume, pagination, and event delivery. All figures are ADP-published as of September 2026; check ADP's developer portal before you size a build around them.

The event rows matter more than they look. The safe pattern is to treat a webhook notification as a trigger to fetch current state, and the retry-and-discard behavior above is why: a failed event disappears after five days, so anything you build that relies on webhooks as a system of record rather than a signal to re-poll will quietly drift out of sync.

Partner and Marketplace integrations: managing a client's credentials

Everything so far assumes one integration talking to one ADP tenant. A Marketplace partner serving many ADP customers has a different problem: credentials multiply per client, and ADP documents up to five separate credential sets a partner manages: inbound Marketplace credentials, outbound Marketplace credentials, partner data-connector credentials, client data-connector credentials, and partner SSO credentials.

Each set has its own lifecycle, and ADP's guidance on all of them is the same: store what ADP issues securely. For the client credentials, partners don't ask each client to generate and hand over a secret. They call ADP's credentials.read endpoint with their partner data-connector credentials, once per subscribed client, which keeps the fan-out from becoming a support burden on top of an engineering one.

For a partner with ten ADP customers, that's up to five credential sets multiplied by ten tenants, each with its own rotation schedule and its own failure mode if one goes stale. Our ADP Workforce Now connector page covers how that fan-out is handled when it's someone else's job to handle it.

That multiplication is exactly the kind of cost that turns "we'll just build it" into a multi-quarter commitment, and it's worth pricing in before you decide which side of that decision you're on.

Build it yourself, or route ADP through a unified API

Add it up: mutual TLS certificate lifecycle, entitlement-aware pagination, tier-specific throttling, and, if you're a partner, five credential sets per client that need issuing, rotating, and storing. None of it is unusual for an enterprise HCM API. All of it is correctness work you have to get right before you write a line of your own product's logic.

Choose to build directly when:

• You have exactly one ADP relationship to support and no plan to add a second HR system
• Your team already owns X.509 certificate lifecycle management for other integrations

Choose to route through a unified API when:

• ADP is one of several HR or payroll systems your product needs to reach
• The credential fan-out in the previous section doesn't scale with your engineering headcount

Bindbee's API connects to 102+ systems, including ADP Workforce Now, through each system's supported API access, with no screen scraping in the path. Data syncs on a 24-hour default that can be adjusted per connection, and webhooks fire when a sync finishes, fails, or finds changed records: the same trigger-then-read pattern this guide recommends for ADP's own events.

What routing through infrastructure like this doesn't remove is the entitlement and role decisions that live inside your customer's ADP tenant; those are the customer's configuration, not something any integration layer can override on their behalf.

The token was always the easy part. Whether you build the certificate handling, the entitlement-aware pagination, and the five-credential fan-out yourself, or hand that architecture to something that already has it, the actual decision is the same one this whole guide has been pointing at: does your team want to own ADP's access model, or just consume what's on the other side of it. See Bindbee's ADP Workforce Now connector, or talk to us about routing ADP through one API.

Frequently asked questions

How long is an ADP Workforce Now API access token valid?

An access token is valid for 60 minutes (3,600 seconds). Reuse it across calls until it is close to expiry, then request a new one. ADP's integration standards say not to request a token for every API call, and never to store or pass tokens in cookies or URL parameters.

Why am I getting an HTTP 403 when my token is valid?

A 403 means the token authenticated correctly but the caller isn't authorized for that resource or scope. Access beyond authentication is gated separately by the API user's role, their data entitlement, and the canonical URI registered for the application in the Consumer Application Registry.

What are the ADP API rate limits?

API Central projects are limited to under 120 requests per 60 seconds with a maximum of 10 concurrent requests. Marketplace partner projects get a higher tier, under 300 requests per 60 seconds with up to 50 concurrent, and either tier returns an HTTP 429 once exceeded.

How many worker records can one call return?

GET /hr/v2/workers returns only the workers the requester is authorized to view, at most 100 per page using OData's $top. Use $skip to page through the rest.

Is the end-user login flow the same as the data-connector auth?

No. End-user login uses OpenID Connect's authorization-code flow, with separate authorize, token, userinfo, and logout endpoints, while the server-to-server data connector authenticates with OAuth client credentials plus mutual TLS. They share the OAuth foundation but solve different problems: one logs in a person, the other authenticates a system.