Gusto Embedded Payroll - Integration Documentation

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Integration Patterns

​

Platform Integration Layer

// Re-exports from @gusto/embedded-react-sdk (configured).
// Note: Gusto docs use Employee.EmployeeList; verify package exports (top-level EmployeeList vs Employee.EmployeeList) at implementation.
export { GustoProvider, EmployeeOnboardingFlow, EmployeeList, componentEvents } from '@gusto/embedded-react-sdk';

export function useGustoConfig(): {
  baseUrl: string;
  companyId: string | null;
  isConnected: boolean;
  isLoading: boolean;
  error: Error | null;
};

export function useGustoConnectionStatus(organizationId: string): {
  status: 'connected' | 'disconnected' | 'error';
  gustoCompanyId: string | null;
  isLoading: boolean;
};

import { GustoProvider, EmployeeOnboardingFlow, useGustoConfig } from '@/platform/gusto';

function HRGustoOnboardingPage() {
  const { baseUrl, companyId, isConnected, isLoading, error } = useGustoConfig();
  if (!isConnected || !companyId) return <EmptyState />;
  return (
    <GustoProvider config={{ baseUrl }}>
      <EmployeeOnboardingFlow companyId={companyId} onEvent={handleEvent} />
    </GustoProvider>
  );
}

​

API Contract: Gusto Proxy

• Receives request from SDK (path + body match Gusto Embedded API 1:1).
• Resolves authenticated user’s organization_id; loads that org’s Gusto OAuth access token from PF-35 (pf_integrations + credentials).
• Adds Authorization: Bearer <token> and x-gusto-client-ip (from X-Forwarded-For or X-Real-IP).
• Forwards to https://api.gusto.com (exact path per Gusto Embedded API docs).
• On 401: attempts token refresh (using stored refresh token). If the authorization server returns a new refresh token in the refresh response, the proxy must persist and replace the old refresh token in the credential store (PF-35 / pf_integrations) so future refreshes use the new value. The retry MUST use the newly issued access token in the Authorization: Bearer <token> header. On refresh or persist failure, return a sanitized error (e.g. 502 “Reconnect to Gusto”) without exposing tokens.

​

Security

• OAuth tokens and refresh tokens only server-side (PF-35 / Vault); never in frontend.
• x-gusto-client-ip (trusted client IP): The Edge Function (or middleware) must derive a trusted client IP as follows:
  • Prefer X-Forwarded-For: use the rightmost entry added by your trusted edge proxy (i.e., the last IP in the chain), since the leftmost is typically the original client and the rightmost is the one added by the proxy closest to this service.
  • Fall back to X-Real-IP only if the request is known to have passed through a trusted proxy that sets it.
  • Otherwise use the connection remote address.
  • The Edge Function must validate/sanitize the chosen IP: parse and canonicalize it, reject private/reserved ranges unless explicitly expected (e.g., internal networks), and verify the request passed through a known proxy list when using forwarded headers. If no trusted IP can be determined, set the header value to “unknown” and log a warning.
• Proxy and company resolution scoped by organization_id; no cross-tenant data.

​

SDK Event Types

​

References

• Spec: specs/pf/specs/PF-65-gusto-embedded-payroll-integration.md
• PF-35: Integration Hub – specs/pf/specs/PF-35-integration-hub.md
• API Contracts: docs/architecture/integrations/API_CONTRACTS.md (proxy to be added)
• Platform Integration Layers: docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md
• Gusto Embedded API: https://docs.gusto.com/embedded-payroll/docs/