Authentication
The SDK sends requests to the backend proxy configured by GustoProvider's config.baseUrl. Your proxy authenticates the user in your application, authorizes their request, and forwards it to the Gusto Embedded API with a Gusto access token. The SDK does not acquire or refresh Gusto tokens.
Gusto access tokens
Gusto tokens authorize your application's API access. They do not encode the permissions of the person signed in to your application.
| Token | Acts on behalf of | Use it for |
|---|---|---|
| System access token | Your application | Application-level operations, such as creating a partner-managed company or subscribing to webhooks. |
| Company access token | A specific company using your application | Company-level operations, such as accessing employees or submitting payroll, within your application's granted API scopes. |
Use a system access token for system-level operations and a company token for regular access to that company's resources. A company token cannot access another company. See the REST API's Authentication and authorization guide for obtaining, storing, and refreshing tokens, and API scopes for the operations your application may perform.
Example: creating and accessing a company
Your backend uses a system access token to create company A and receives its UUID and access and refresh tokens.
When EmployeeManagement.EmployeeList renders, the SDK requests employees for the supplied companyId. Your backend authenticates the user, authorizes their access to the requested employees, and then selects the stored token for company A.
If your backend forwards a request for company B using company A's token, Gusto rejects the request.
Keep Gusto access tokens, refresh tokens, and application credentials on your backend. Select a company token only after establishing that the authenticated user may access that company. Gusto's company boundary does not determine which resources that user may access within the company.
Your application's users
Your proxy authenticates each session and determines which companies and resources the user may access. The authorized company determines which Gusto token to use; the session's permissions determine which requests to forward.
What Gusto sees: Your application requests company A's payrolls using a company token. Gusto checks the token, API scopes, and company boundary.
What your application sees: The request comes from a specific user session. Your proxy must decide whether that person may access company A's payrolls before forwarding the request.
For example, your application might authorize a payroll administrator to read company A's payrolls. If a contractor self-onboarding session attempts the same request, your proxy must reject it before it reaches Gusto:
Gusto does not authenticate the person signed in to your application or evaluate their session permissions. Even when a company token permits an operation, your proxy must reject requests outside the user's permissions.
Use those permissions to decide which SDK components to display, and enforce them on every proxy request. See Reviewing SDK API access to identify the requests your components use when defining your proxy's authorization policies.
Connecting the SDK to your proxy
Set GustoProvider's config.baseUrl to your proxy's address. Use your application's authentication mechanism to identify the user making each request. If that mechanism requires request headers, the SDK supports static headers through config.headers and headers computed at request time through request interceptors. These browser-side headers authenticate requests to your proxy; supply Gusto credentials only on the backend request to the API.
Your proxy forwards the authorized request and returns the API response to the SDK. Add the x-gusto-client-ip header using a client IP established by your backend; signature workflows require it. We also recommend forwarding the SDK's X-Gusto-SDK-Version request header so Gusto can identify the SDK version when investigating API traffic.
The demo application provides a runnable example of token management and forwarding. Its proxy does not currently implement user authentication or authorization.