Prerequisites

• An active ADP Workforce Now account
• An active subscription to ADP API Central for ADP Workforce Now, purchased from the ADP Marketplace by your ADP account administrator. API Central is a paid add-on. Without it, ADP does not issue API credentials for custom integrations.
• Access to API Central with the Project user and Certificate user roles (the administrator who activated API Central can assign these under Members)
• From API Central: a Client ID, a Client Secret, a Certificate (.pem) and its matching Private Key

Create an API Central project and get your Client ID and Client Secret

1. Go to api-central.adp.com and sign in with your ADP credentials.

2. Click Projects in the left menu, then Create Project.

3. Enter a project name, e.g. Matia, and a short description.

4. Select a use case. Employee Sync covers worker demographic and employment data. Add Time, Attendance and Schedules, PTO/Time Off or Payroll Input if you plan to sync those streams as well. You can add more APIs to the project later with the API Discovery tool.

5. Click Create Project. ADP generates the project's credentials automatically.

6. Open the project's Credentials tab and make a note of the Client ID and Client Secret.

   Note: You can reset the credentials at any time from the same tab. Resetting issues a new client secret and breaks any Matia connection that uses the old one.

Generate your certificate and private key

ADP requires every API call to be made over mutual TLS, so Matia needs an ADP-signed certificate together with the private key that matches it. API Central generates both for you.

1. Open your project and select Certificate (it is also Step 1 of the project setup), then click Manage Certificate.

2. Follow the guided steps to request a new certificate. ADP signs it in real time.

3. Copy or download the Private Key and save it to a file, e.g. matia_adp.key. Keep the full text, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.

   Note: The private key is shown only once. If you lose it, request a new certificate.

4. Click Download to save the Certificate as a .pem file, e.g. matia_adp.pem.

   Note: ADP certificates expire. API Central starts notifying you 60 days before the expiry date. When you renew, upload the new certificate and private key to the Matia connection settings.

Already have a private key? You can instead generate a Certificate Signing Request (CSR) with OpenSSL and submit it to ADP's Certificate Signing Tool. Leave Country, State, Locality and Challenge password blank, set Organization Name to the exact name your organization is registered under with ADP, and set Common Name to your company name followed by MutualSSL with no spaces or special characters, e.g. AcmeMutualSSL. The tool asks for your ADP client ID, which for Workforce Now is everything after the @ in your ADP login name. Full instructions are in ADP's CSR guide.

Setup Guide

1. Enter the Client ID from your API Central project.

2. Enter the Client Secret from your API Central project.

3. Paste the full contents of your Web Services Certificate (matia_adp.pem), including the header and footer lines. For example:

   -----BEGIN CERTIFICATE-----
   <certificate body>
   -----END CERTIFICATE-----

4. Paste the full contents of your Private Key (matia_adp.key), including the header and footer lines. For example:

   -----BEGIN PRIVATE KEY-----
   <private key body>
   -----END PRIVATE KEY-----

5. Enter a Name for the connector.

6. (Optional) Enter a Description for the connector.

7. Select the Owner of the connector.

8. (Optional) Verify that your ADP Workforce Now account is successfully connected by clicking on Test Connection.

9. Click Connect.

Notes

• Matia connects to the ADP API using the OAuth 2.0 client credentials flow over mutual TLS. Access tokens are generated and refreshed automatically from your client ID, client secret, certificate and private key. You never need to copy or rotate tokens manually.
• The certificate and private key must be a matching pair. If Test Connection fails with a TLS or handshake error, confirm you pasted the certificate and key from the same API Central certificate request.
• If a stream fails with a permissions (403) error, the project is missing that API. In API Central, open your project and add the missing API with the API Discovery tool. The change takes effect on the next sync.
• If you reset the client secret or renew the certificate in API Central, remember to update the credentials in the Matia connection settings.