How to Integrate Lovable with ADP

Go to developers.adp.com and sign in or create a developer account. Navigate to 'My Apps' and click 'Create App'. Choose the appropriate API product — for worker data and pay statements, select 'HR and Payroll' from the product catalog. Give your app a name and description, then submit for approval. ADP developer sandbox apps are typically approved within 1-2 business days. Once approved, open your app from the 'My Apps' dashboard. In the app detail page, you'll find: Client ID (a UUID-formatted identifier), Client Secret (a long random string), and an option to download the SSL Certificate. Click 'Download Certificate' to get a .zip file containing your client certificate (.pem) and private key. These files together are your mTLS credentials — they prove your application's identity to ADP's servers. The ADP developer sandbox provides a realistic dataset of fictional employees, pay statements, and organizational units. The sandbox base URL is https://api.adp.com (same as production) but uses separate credentials that only return synthetic data. This lets you build and test your integration completely before handling any real employee data. For accessing a real company's ADP data (production), the company's ADP administrator must grant your application access to their organization through the ADP Marketplace. This is a separate step from registering your developer app — your app acts as a platform, and each client company authorizes it.

ADP credentials require special handling in Cloud Secrets because they include both text values (client ID, client secret) and a multi-line certificate file. Open your Lovable project, click the '+' icon in the top-right to open panels, and select 'Cloud'. Expand the Secrets section. Add the following secrets one at a time. First, ADP_CLIENT_ID — paste your application's Client ID UUID. Second, ADP_CLIENT_SECRET — paste the client secret string. Third, ADP_CERT_PEM — paste the entire contents of your client certificate .pem file, including the BEGIN CERTIFICATE and END CERTIFICATE lines. The multi-line content will be stored correctly in the secret value. Fourth, ADP_CERT_KEY — paste the entire private key file contents. Also add ADP_API_BASE with value 'https://api.adp.com' for the sandbox and production environments (they use the same base URL but different credentials). Add ADP_ENVIRONMENT with value 'sandbox' or 'production' to indicate which credential set is active. Storing the certificate as a Cloud Secret rather than a file is necessary because Lovable's Edge Functions run in Deno Deploy's serverless environment — there's no persistent filesystem. The certificate content is read from the environment variable, written to a temporary in-memory location, and used for the TLS handshake on each request. This is standard practice for mTLS in serverless environments.

ADP uses OAuth2 client credentials flow (machine-to-machine), where your application authenticates itself rather than a user. The token endpoint requires both the client credentials AND the mTLS certificate — without both, the request is rejected. Access tokens expire after 3600 seconds (1 hour) and should be cached in Supabase to avoid re-authenticating on every request. The token request is a POST to https://accounts.adp.com/auth/oauth/v2/token with the grant_type=client_credentials parameter in the body and Basic HTTP authentication headers using your client_id and client_secret. The critical additional requirement is presenting your client SSL certificate during the TLS handshake. In Deno's environment, mTLS is handled through the native fetch API with TLS configuration options. You provide the certificate and key content (read from Deno.env) to configure a custom TLS client for the token request. Subsequent API calls also require the same mTLS configuration. Cache the token in a Supabase table (adp_tokens with columns: token, expires_at) and check the cache before each token request. If the cached token expires in less than 5 minutes, proactively refresh it. This caching is important because ADP's token endpoint is rate-limited and slow compared to typical OAuth providers.

1// supabase/functions/adp-auth/index.ts
2import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
3import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
4
5const corsHeaders = {
6  "Access-Control-Allow-Origin": "*",
7  "Access-Control-Allow-Methods": "POST, OPTIONS",
8  "Access-Control-Allow-Headers": "Content-Type, Authorization",
9};
10
11const ADP_TOKEN_URL = "https://accounts.adp.com/auth/oauth/v2/token";
12
13serve(async (req) => {
14  if (req.method === "OPTIONS") return new Response(null, { headers: corsHeaders });
15
16  const supabase = createClient(
17    Deno.env.get("SUPABASE_URL") ?? "",
18    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY") ?? ""
19  );
20
21  // Check cache first
22  const { data: cached } = await supabase
23    .from("adp_tokens")
24    .select("token, expires_at")
25    .order("expires_at", { ascending: false })
26    .limit(1)
27    .single();
28
29  if (cached && new Date(cached.expires_at) > new Date(Date.now() + 300_000)) {
30    return new Response(JSON.stringify({ access_token: cached.token }), {
31      headers: { ...corsHeaders, "Content-Type": "application/json" },
32    });
33  }
34
35  // Request new token
36  const clientId = Deno.env.get("ADP_CLIENT_ID") ?? "";
37  const clientSecret = Deno.env.get("ADP_CLIENT_SECRET") ?? "";
38  const credentials = btoa(`${clientId}:${clientSecret}`);
39
40  try {
41    // Note: Deno's fetch supports client certificates via TLS options
42    // In production Deno Deploy, use the cert/key env vars with a custom TLS client
43    const res = await fetch(ADP_TOKEN_URL, {
44      method: "POST",
45      headers: {
46        "Authorization": `Basic ${credentials}`,
47        "Content-Type": "application/x-www-form-urlencoded",
48      },
49      body: "grant_type=client_credentials",
50    });
51
52    const data = await res.json();
53    if (!data.access_token) throw new Error(data.error_description ?? "Token request failed");
54
55    const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
56    await supabase.from("adp_tokens").insert({ token: data.access_token, expires_at: expiresAt });
57
58    return new Response(JSON.stringify({ access_token: data.access_token }), {
59      headers: { ...corsHeaders, "Content-Type": "application/json" },
60    });
61  } catch (err) {
62    return new Response(JSON.stringify({ error: err.message }), {
63      status: 500,
64      headers: { ...corsHeaders, "Content-Type": "application/json" },
65    });
66  }
67});

With authentication working, create the main data Edge Function that fetches worker information from ADP's HR API. The ADP Worker API follows the HATEOAS pattern — responses include pagination links and resource links rather than embedding all data. For a worker list, the base endpoint is GET /hr/v2/workers. The response includes each worker's associateOID (unique identifier), name parts (given name, family name), work email, department (via organization units), job title (via job code), hire date, and employment status. The data is deeply nested — for example, job title lives at workers[n].businessCommunications... or workers[n].workAssignments[0].jobTitle.shortName depending on the specific ADP product and version your organization uses. Page through results using the $top (page size) and $skip (offset) parameters. ADP's default page size is 25 workers; for organizations with hundreds of employees, implement pagination in your Edge Function. Store worker data in a Supabase employees table and refresh it periodically rather than calling ADP on every page load — ADP's API is not designed for high-frequency read patterns.

With worker data syncing to Supabase, build the HR dashboard frontend. The dashboard should query the Supabase employees table directly for most views — only the sync action calls ADP. This architectural separation means the dashboard loads fast (reading from a local database) even though ADP's API is relatively slow. Create three main sections: an employee directory with search and filter by department, an org chart view showing reporting relationships, and a sync status panel showing when data was last updated from ADP and allowing manual re-sync. For the employee directory, display employees as cards or rows in a table with their name, job title, department, and email. Add a search input that filters the Supabase query using ilike for case-insensitive name and title matching. Add a department filter dropdown populated from distinct department values in the table. For the org chart, query employees with their manager relationships (if your ADP data includes manager OIDs, store these in the table and use them to build a tree). A simple org chart can be rendered using a recursive React component that nests employee cards. Add a 'Sync from ADP' button in the dashboard header that calls the adp-workers Edge Function with action='sync' and shows a loading spinner with 'Syncing employee data...' text during the operation.