ADP

Navigate to the ADP Developer Portal at developers.adp.com and sign in with your ADP credentials. If you don't yet have Developer Portal access, contact your organization's ADP account manager — access may need to be provisioned separately from your main ADP subscription. Create a new API application in the portal. During registration, select the API products you need access to: Workers API for employee records, Pay API for payroll summaries, and/or Time & Attendance API for time cards. Each product may require separate approval from ADP. Once your application is approved (this can take days to weeks depending on your ADP relationship), the portal provides: - Client ID — a public identifier for your application - Client Secret — a private credential for the OAuth2 token exchange - X.509 Certificate (PEM format) — the public part of your mTLS client certificate - Private Key (PEM format) — the matching private key for the certificate Download all four values and store them immediately in a secure credential store (like 1Password or your organization's secrets manager). The private key especially must never be committed to version control, stored in plain text files, or placed in any system that logs environment variables. Note the API base URLs for your environment: - Production: https://api.adp.com (data), https://accounts.adp.com/auth/oauth/v2/token (token) - Sandbox: https://api.adpapis.com (data), https://accounts.adpapis.com/auth/oauth/v2/token (token) Start with the sandbox environment to verify connectivity before pointing at production data.

The Cloudflare Worker proxy is the core of this integration. It performs ADP's mTLS OAuth2 token exchange, caches the token for its lifetime (~3,600 seconds), and exposes scoped REST endpoints that Bubble calls with a simple API key header. Create a new Cloudflare Worker in the Cloudflare dashboard (workers.cloudflare.com). Name it something like 'adp-proxy'. In the Worker's environment settings, add the following secret variables (use the 'Add variable' → 'Encrypt' option so they are never visible after saving): - ADP_CLIENT_ID - ADP_CLIENT_SECRET - ADP_CERT_PEM (paste the full certificate PEM including headers) - ADP_PRIVATE_KEY_PEM (paste the full private key PEM including headers) - ADP_PROXY_API_KEY (a random secret string you generate — this is what Bubble uses to authenticate to your proxy) - ADP_TOKEN_ENDPOINT (e.g., https://accounts.adp.com/auth/oauth/v2/token) - ADP_API_BASE_URL (e.g., https://api.adp.com) The Worker code validates the incoming X-Proxy-Key header against ADP_PROXY_API_KEY, checks for a cached token, exchanges credentials for a new token using ADP's mTLS endpoint when needed, caches the token with expiry tracking, and routes requests to the appropriate ADP endpoint based on the URL path (e.g., /workers routes to ADP's Workers API, /pay-summary routes to ADP's Pay API). Once deployed, test the Worker using the Cloudflare dashboard's test interface by sending a GET request to https://your-worker.workers.dev/workers with the X-Proxy-Key header. A successful first response confirms the mTLS handshake, token exchange, and ADP data retrieval are all working.

1// Cloudflare Worker proxy for ADP mTLS integration
2// Deploy to Cloudflare Workers — requires secrets: ADP_CLIENT_ID, ADP_CLIENT_SECRET,
3// ADP_CERT_PEM, ADP_PRIVATE_KEY_PEM, ADP_PROXY_API_KEY, ADP_TOKEN_ENDPOINT, ADP_API_BASE_URL
4
5let cachedToken = null;
6let tokenExpiresAt = 0;
7
8async function getAdpToken(env) {
9  const now = Date.now() / 1000;
10  if (cachedToken && now < tokenExpiresAt - 60) {
11    return cachedToken;
12  }
13
14  // ADP requires form-url-encoded body, NOT JSON
15  const body = new URLSearchParams({
16    grant_type: 'client_credentials',
17    client_id: env.ADP_CLIENT_ID,
18    client_secret: env.ADP_CLIENT_SECRET
19  });
20
21  // mTLS: pass cert and key via fetch options (Cloudflare Workers support)
22  const tokenResponse = await fetch(env.ADP_TOKEN_ENDPOINT, {
23    method: 'POST',
24    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
25    body: body.toString(),
26    // Note: Cloudflare Workers handle mTLS via wrangler.toml mtls_certificates
27    // or via the fetch() cf.clientCertificate option in enterprise plans
28  });
29
30  if (!tokenResponse.ok) {
31    throw new Error(`ADP token exchange failed: ${tokenResponse.status}`);
32  }
33
34  const data = await tokenResponse.json();
35  cachedToken = data.access_token;
36  tokenExpiresAt = now + (data.expires_in || 3600);
37  return cachedToken;
38}
39
40export default {
41  async fetch(request, env) {
42    // Validate proxy API key
43    const proxyKey = request.headers.get('X-Proxy-Key');
44    if (proxyKey !== env.ADP_PROXY_API_KEY) {
45      return new Response('Unauthorized', { status: 401 });
46    }
47
48    const url = new URL(request.url);
49    const path = url.pathname; // e.g. /workers, /pay-summary
50
51    try {
52      const token = await getAdpToken(env);
53      const adpUrl = `${env.ADP_API_BASE_URL}${path}${url.search}`;
54
55      const adpResponse = await fetch(adpUrl, {
56        method: request.method,
57        headers: {
58          'Authorization': `Bearer ${token}`,
59          'Content-Type': 'application/json'
60        },
61        body: request.method !== 'GET' ? await request.text() : undefined
62      });
63
64      const responseData = await adpResponse.json();
65      return new Response(JSON.stringify(responseData), {
66        status: adpResponse.status,
67        headers: { 'Content-Type': 'application/json' }
68      });
69    } catch (err) {
70      return new Response(JSON.stringify({ error: err.message }), {
71        status: 500,
72        headers: { 'Content-Type': 'application/json' }
73      });
74    }
75  }
76};

With the Cloudflare Worker proxy running, Bubble now calls a standard HTTPS endpoint — no mTLS required from Bubble's side. Open your Bubble app's Plugins tab and install 'API Connector' by Bubble (free, if not already installed). Click 'Add another API' and name it 'ADP Proxy'. Set the base URL to your Cloudflare Worker URL: https://your-worker.workers.dev In the 'Shared headers for all calls' section, add one header: - Key: X-Proxy-Key - Value: the ADP_PROXY_API_KEY secret you set in the Worker - Mark as Private — click the Private checkbox to ensure this key is never sent to the browser Add your first call — the Workers (employee) endpoint: - Name: Get Employees - Method: GET - URL: https://your-worker.workers.dev/workers - Use as: Data - Add URL parameters: - $top: 100 (max records per page) - $skip: 0 (starting offset, make this dynamic for pagination) Click 'Initialize call'. The proxy fetches from ADP and returns employee data. Bubble detects the response fields. ADP's Workers response is deeply nested — common fields to look for after proxy or transformer flattening: - associateOID (ADP's internal employee identifier) - person/legalName/formattedName (full name) - workAssignments[0]/jobTitle - workAssignments[0]/hireDate - workAssignments[0]/assignmentStatus/statusCode/codeValue (ACTIVE, TERMINATED, etc.) Add similar GET calls for pay summaries (/pay-summary) and time cards (/time-cards) following the same pattern.

1{
2  "api_name": "ADP Proxy",
3  "base_url": "https://your-worker.workers.dev",
4  "shared_headers": [
5    {
6      "key": "X-Proxy-Key",
7      "value": "<private>",
8      "private": true
9    }
10  ],
11  "calls": [
12    {
13      "name": "Get Employees",
14      "method": "GET",
15      "url": "https://your-worker.workers.dev/workers",
16      "use_as": "Data",
17      "params": [
18        { "key": "$top", "value": "100" },
19        { "key": "$skip", "value": "<dynamic>", "initial": "0" }
20      ]
21    },
22    {
23      "name": "Get Pay Summary",
24      "method": "GET",
25      "url": "https://your-worker.workers.dev/pay-summary",
26      "use_as": "Data",
27      "params": [
28        { "key": "payPeriodStart", "value": "<dynamic>" },
29        { "key": "payPeriodEnd", "value": "<dynamic>" }
30      ]
31    },
32    {
33      "name": "Get Time Cards",
34      "method": "GET",
35      "url": "https://your-worker.workers.dev/time-cards",
36      "use_as": "Data",
37      "params": [
38        { "key": "$top", "value": "100" },
39        { "key": "$skip", "value": "<dynamic>", "initial": "0" },
40        { "key": "weekStart", "value": "<dynamic>" }
41      ]
42    }
43  ]
44}

With the API Connector calls initialized, build the HR dashboard UI in Bubble's Design editor. Employee directory page: Add a Repeating Group and set its Data source to 'Get data from an external API' → 'ADP Proxy - Get Employees'. Set $skip to (Current page - 1) × 100 for offset pagination (Bubble's page numbers start at 1, so subtract 1 and multiply by your page size). Set $top to 100. Inside the Repeating Group cell, add text elements for each employee field. ADP returns deeply nested JSON — after initialization, look for the auto-detected fields in Bubble's expression builder. If your proxy flattens the fields (recommended), you'll see straightforward fields like name, jobTitle, status, hireDate. If not, navigate nested paths via Bubble's data expression dot notation: Current cell's ADP Proxy Get Employees's workAssignments:first item's jobTitle. Add a status color indicator: conditional formatting on a color indicator element — ACTIVE = green, TERMINATED = red, LEAVE_OF_ABSENCE = orange. Add pagination controls: Previous and Next buttons that change a numeric page custom state. Bind $skip dynamically to (custom_page - 1) × 100. Filter options: Add dropdowns for department and status. For department filtering, pass the department name as an additional OData $filter parameter to the proxy URL if your proxy supports it, or filter client-side using Bubble's ':filtered' operator on the Repeating Group's data source. Privacy: Set up privacy rules in Bubble's Data tab for any Things you create to store ADP employee data. Employee PII (name, salary, employment status) requires strict privacy rules — typically limited to logged-in admins with a specific role.

For time-card approval write-backs (PATCH /time-cards/{id}/approval), add a new Action call in the API Connector: - Name: Approve Time Card - Method: POST or PATCH (check your ADP API product documentation — the specific endpoint format varies by ADP product tier) - URL: https://your-worker.workers.dev/time-cards/[id]/approval (with dynamic path param for the time card ID) - Body type: JSON - Body: the approval payload per ADP's specification - Use as: Action IMPORTANT: Write permissions (POST/PATCH to ADP) require explicit write scope in your ADP Developer Portal app registration. If you only requested read access during registration, write calls will return 403 Forbidden. Update your ADP app's permissions in the Developer Portal and confirm approval before building write workflows. Optional nightly sync (requires paid Bubble plan — Starter $32/mo+): Some use-cases benefit from syncing ADP employee data into a Bubble database nightly for faster searches and reporting. Create a Recurring Backend Workflow (Settings → API → Backend Workflows → Recurring) that runs daily at a low-traffic time: 1. Call 'Get Employees' with $skip=0, $top=100 → create or update Bubble Things for each employee 2. Schedule another API workflow with $skip=100 for the next 100 records 3. Continue until no more records are returned This pattern consumes significant Workload Units (one WU per API call + one per database write). For large organizations, evaluate whether the WU cost of nightly sync is worthwhile compared to live API calls on each page load. RapidDev's team has helped enterprise HR teams build ADP-connected Bubble tools with complex sync architectures — free scoping call at rapidevelopers.com/contact.

1{
2  "call_name": "Approve Time Card",
3  "method": "POST",
4  "url": "https://your-worker.workers.dev/time-cards/<dynamic_id>/approval",
5  "use_as": "Action",
6  "body_type": "JSON",
7  "body": {
8    "approvalStatus": "approved",
9    "approvedBy": "<dynamic_manager_id>"
10  }
11}
12
13// ADP OData pagination pattern:
14// Page 1: $top=100&$skip=0
15// Page 2: $top=100&$skip=100
16// Page 3: $top=100&$skip=200
17// Continue until response returns fewer records than $top