We have a demo environment in CodeSandbox. You can view the project setup there which puts together what you are going to see in this guide with a working example.

To get started with the Gusto Embedded React SDK, first install it from NPM via the package manager of your choice. You can see the SDK published to NPM here at @gusto/embedded-react-sdk.

In this case, installing via NPM:

npm i @gusto/embedded-react-sdk

The GustoProvider is used to configure the SDK at the application level. It must wrap the top-level component tree (typically at the root of the application) to ensure SDK components have access to the necessary configurations.

import { GustoProvider } from '@gusto/embedded-react-sdk'

function App() {
  return <GustoProvider config={{ baseUrl: '/proxy-url/' }}>...</GustoProvider>
}

export default App

The baseUrl property is configured with the address of your backend proxy which is detailed further in the following section.

When building with the React SDK, a backend proxy is required. React SDK components do not make calls to the Gusto Embedded API directly. Instead, the baseUrl configuration defines the URL of your proxy server. This proxy layer gives you complete control over requests sent to Gusto, which is essential for:

1. Authentication
2. Providing the user IP address for form signing operations

The React SDK is designed to mirror the Gusto Embedded API Reference with a 1:1 mapping of endpoints. The SDK maintains consistent naming conventions, parameters, and response structures with the Gusto API.

Your proxy server simply needs to forward any incoming SDK requests to the corresponding Embedded API endpoints. The proxy's main task is adding the necessary authentication headers before forwarding the request onwards. Since the SDK requests are already in the Embedded API format, no extra endpoint mapping or request transformation is required.

The proxy layer allows for authentication. The recommended approach is to use a backend service that acquires OAuth2 tokens from the Gusto Embedded API for authenticated users and proxies API calls using those tokens. Learn more about configuring this and setting up authentication in the Authentication section.

Some UI workflows require users to sign forms, which need the user's IP address for security purposes. To prevent vulnerabilities such as IP address spoofing, this information must be provided by your proxy server rather than collected client-side.

Your proxy server can provide the IP address by adding the x-gusto-client-ip header with the user IP address to all forwarded requests on the backend. By setting this header once in your proxy it will be configured for all form signing operations.

Your proxy is also the authorization layer between your users and the Gusto API. Because users can make API requests outside the SDK UI, authorization must be enforced server-side. The Gusto API provides application-level protections (scopes, company-bound tokens, rate limits), but user-level authorization is your responsibility.

At a minimum, your proxy should:

• Authenticate every request -- verify the user's session, not just at login
• Allowlist endpoints -- only forward requests to API endpoints your app actually uses
• Validate resource ownership -- ensure users can only access their own resources (e.g., their own employee ID)
• Log proxied requests -- maintain audit logs for monitoring and incident response

For detailed guidance, endpoint allowlist tooling, and runnable examples, see the Proxy Security: Partner Guidance.

The Gusto Embedded React SDK ships with preliminary styles for the UI components as a baseline. Those can be included by importing the following stylesheet:

import '@gusto/embedded-react-sdk/style.css'

See Customizing SDK UI for complete guidance on UI customization and making the SDK take on the look and feel of your application.