> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ADP API Authentication

> How Toku authenticates with the ADP API using OAuth 2.0 client credentials and mutual TLS

Toku connects to ADP Workforce Now using [ADP's OAuth 2.0 client credentials flow combined with mutual TLS](https://developers.adp.com/articles/general/introduction-mutual-ssl). Every call — token requests and API requests alike — is authenticated with both a client ID/secret and an ADP-issued X.509 client certificate.

## OAuth 2.0 + Mutual TLS Flow

<Steps>
  <Step title="Issue credentials">
    Your ADP administrator creates a dedicated API project for Toku in ADP API Central, which issues the client ID, client secret, and X.509 client certificate and key. (For ADP Marketplace subscriptions, credentials are granted through the Consent Manager instead.)
  </Step>

  <Step title="Request a token">
    Toku's backend presents the certificate and client credentials to ADP's token endpoint and receives a bearer access token.
  </Step>

  <Step title="Refresh">
    Tokens expire after 60 minutes. Toku requests a fresh token automatically before expiry — the connection stays live without manual intervention.
  </Step>
</Steps>

```bash theme={null}
# Token request (performed by Toku's backend)
curl --request POST \
  --url 'https://accounts.adp.com/auth/oauth/v2/token' \
  --cert toku.crt --key toku.key \
  --user '<client_id>:<client_secret>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'
```

A successful response:

```json theme={null}
{
  "access_token": "ba55dc8e-a532-4a9d-9c3c-4b7b6a9e2f10",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Authenticated API requests carry the bearer token **and** the same client certificate:

```bash theme={null}
curl "https://api.adp.com/hr/v2/workers" \
  --cert toku.crt --key toku.key \
  -H "Authorization: Bearer <access_token>"
```

## Mutual TLS Requirements

| Requirement        | Detail                                                                    |
| ------------------ | ------------------------------------------------------------------------- |
| Client certificate | ADP-issued X.509 certificate and private key, presented on **every** call |
| Hosts              | Required for both `accounts.adp.com` (tokens) and `api.adp.com` (APIs)    |
| TLS version        | TLS 1.2                                                                   |
| Token lifetime     | 3,600 seconds (60 minutes), auto-refreshed by Toku                        |

Because ADP validates the certificate on every request, a leaked client secret alone cannot access your data — the certificate is required as a second, independent factor.

## Environments

| Environment | Token endpoint                                    |
| ----------- | ------------------------------------------------- |
| US          | `https://accounts.adp.com/auth/oauth/v2/token`    |
| EU          | `https://accounts.eu.adp.com/auth/oauth/v2/token` |

<Note>
  Credentials and certificates are generated in your own ADP API Central project, so your ADP admin controls (and can revoke) Toku's access at any time. See [ADP's developer documentation](https://developers.adp.com/) and the [mutual TLS guide](https://developers.adp.com/articles/general/introduction-mutual-ssl) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Employee Sync" icon="users" href="/integrations/adp/employee-sync">
    How Toku reads your worker roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/adp/payroll-sync">
    How Toku tracks pay cycles and payroll output
  </Card>
</CardGroup>