Skip to main content

Gusto

Gusto is a comprehensive payroll, benefits, and HR platform designed for small to medium-sized businesses. With Gusto, organizations can manage employee payroll processing, benefits administration, time tracking, contractor payments, compliance, and HR tasks all in one integrated platform.

Authentication Types​

Gusto supports 1 authentication method:

  • OAuth - Connect users with their Gusto company accounts through OAuth 2.0 authorization.
    • Pros: Secure, granular permission control, per-user access tracking, refresh tokens for long-lived access
    • Cons: Requires Gusto Developer Portal access to create app, requires app review and approval for production access
    • Best for: Production integrations, organizations with compliance requirements, secure multi-user access

Setting up OAuth​

To use Gusto with Webrix, you need to create a Gusto application and configure OAuth authentication.

1. Create a Gusto Developer Account​

  1. Go to the Gusto Developer Portal

  2. Sign in with your Gusto account credentials

  3. If you don't have a Gusto account, you'll need to create one first

tip

Only Primary Admins or Full Access Admins can authorize applications and access the Developer Portal.

2. Create a New Application​

  1. In the Developer Portal, click Create New App

  2. Fill in your application details:

    • App Name: Enter a descriptive name (e.g., "Webrix Integration")
    • App Description: Describe what your integration does
    • App Website: Your company or app website URL

  3. Click Create App

3. Configure OAuth Settings​

  1. In your app settings, find the OAuth section

  2. Copy the Redirect URI from Webrix and add it to your Gusto app:

    • In Webrix, go to Integrations → New → Built-in → Gusto
    • Copy the Redirect URI shown in the OAuth configuration
    • Paste it into the Redirect URIs field in your Gusto app
    • Click Add

  3. Copy your Client ID and Client Secret from the Gusto app

Important

Keep your Client Secret secure. Never commit it to version control or share it publicly.

4. Request API Scopes​

  1. In your Gusto app settings, go to the API Scopes section

  2. Request the scopes your integration needs. Common scopes include:

    • companies:read - View company information
    • employees:read - View employee data
    • payrolls:read - View payroll information
    • employee_benefits:read - View employee benefits
    • contractors:read - View contractor information
    • time_off:read - View time off policies and requests

  3. Provide a detailed explanation of why you need each scope

Scope Selection

Only request the minimum scopes necessary for your use case. This helps users feel confident about data access and speeds up the app review process.

5. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Gusto and click Use

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID in the Client ID field

  5. Paste your Client Secret in the Client Secret field

  6. Select the scopes you want to request (must match what was approved in your Gusto app)

  7. Click Save Changes

6. Test with Demo Environment​

  1. During development, your app will access the demo environment at api.gusto-demo.com

  2. Click Connect in Webrix to test the OAuth flow

  3. You'll be redirected to Gusto to authorize the app

  4. Select the company you want to provide access to

  5. Review the requested permissions and click Authorize

  6. You'll be redirected back to Webrix with a successful connection

Multi-Company Access

As of API version v2023-05-01, multi-company administrators must complete the OAuth flow separately for each company they want to provide access to. Each access token is restricted to a single company.

7. Submit for Production Approval​

  1. Once you've tested your integration in the demo environment, submit your app for review

  2. In the Gusto Developer Portal, click Request Production Access

  3. Provide detailed information about:

    • Your integration's purpose and use cases
    • Which API endpoints you'll use
    • How you handle user data and security
    • Your company information and contact details

  4. Gusto will review your application (typically 2-4 weeks)

  5. Once approved, update your Webrix connector to use the production environment

Production Access Required

All integrations must go through Gusto's review and approval process before accessing production data. Plan accordingly for your launch timeline.

Troubleshooting​

Redirect URI Mismatch Error​

If you see "redirect_uri_mismatch" error during OAuth authorization.

Cause: The redirect URL configured in your Gusto app doesn't match the one being used during the OAuth flow.

Solution:

  1. Copy the exact Redirect URI from Webrix (including https:// and any trailing slashes)
  2. Go to your Gusto app in the Developer Portal → OAuth settings
  3. Ensure the URL is added exactly as shown in Webrix
  4. Remove any duplicate or incorrect redirect URIs
  5. Save the changes and try connecting again

Insufficient Permissions Error​

Users see "insufficient permissions" or "access_denied" when trying to authorize.

Cause: The user doesn't have sufficient permissions in Gusto to authorize applications.

Solution:

  1. Ensure the user is a Primary Admin or Full Access Admin in Gusto
  2. Only these roles can authorize new applications
  3. If needed, have a Gusto admin grant the appropriate permissions
  4. Try the authorization flow again

Scope Rejection in Production​

API calls fail with "insufficient_scope" or scope-related errors in production.

Cause: Your production app hasn't been granted the required scopes by Gusto during the review process.

Solution:

  1. Verify which scopes were approved for your app in the Developer Portal
  2. Check that you're not requesting unapproved scopes in your API calls
  3. If you need additional scopes, contact [email protected]
  4. Provide justification for why you need the additional scopes
  5. Wait for approval before using the new scopes

Token Expiration Issues​

Access tokens expire and API calls start failing with 401 errors.

Cause: Gusto access tokens expire after 7200 seconds (2 hours).

Solution:

  1. Implement automatic token refresh using the refresh token
  2. Refresh tokens proactively before they expire rather than waiting for 401 errors
  3. Handle 401 responses by refreshing the token and retrying the request
  4. Ensure your refresh token is being stored securely

Company Selection Required​

OAuth flow fails or user can't complete authorization.

Cause: Starting with API version v2023-05-01, users must explicitly select which company to authorize.

Solution:

  1. During the OAuth flow, users must select a specific company
  2. Multi-company admins need to complete OAuth separately for each company
  3. Ensure your integration handles company-specific access tokens correctly
  4. If a user needs access to multiple companies, they must authorize each one individually

Rate Limiting​

API requests fail with 429 (Too Many Requests) errors.

Cause: Gusto enforces rate limits to ensure platform stability.

Solution:

  1. Implement exponential backoff retry logic for rate-limited requests
  2. Cache data where appropriate to reduce API calls
  3. Use batch operations when available
  4. Monitor the X-RateLimit-* headers in API responses
  5. Consider spreading requests over time rather than making bulk calls
  6. Contact Gusto support if you consistently hit rate limits with normal usage

Demo vs Production Environment​

Integration works in demo but fails in production, or vice versa.

Cause: Different base URLs for demo (api.gusto-demo.com) and production (api.gusto.com).

Solution:

  1. Verify you're using the correct base URL for your environment:
    • Demo/Development: https://api.gusto-demo.com
    • Production: https://api.gusto.com
  2. Ensure your Webrix connector configuration matches your environment
  3. Remember that demo data and production data are completely separate
  4. Test thoroughly in demo before requesting production access

Missing Employee Data​

Employee records are incomplete or missing expected fields.

Cause: Some employee data requires specific scopes or include parameters.

Solution:

  1. Check that you have the required scopes:
    • compensations:read for compensation data
    • custom_fields:read for custom field values
    • company_admin:read for admin information
  2. Use the include parameter to fetch related data (e.g., include=all_compensations,current_home_address)
  3. Verify the employee's onboarding is complete (incomplete onboarding may result in missing data)
  4. Check if the employee is terminated (terminated employees may have limited data access)

Onboarding Status Confusion​

Employees show unexpected onboarding statuses or can't be added to payroll.

Cause: Gusto has multiple onboarding states that affect data availability and payroll eligibility.

Solution:

  1. Use the Get Employee Onboarding Status tool to check detailed onboarding progress
  2. Common statuses:
    • admin_onboarding_incomplete - Admin hasn't finished setup
    • self_onboarding_invited - Employee invited but hasn't started
    • self_onboarding_review - Employee finished, waiting for admin review
    • onboarding_completed - Fully onboarded and payroll-ready
  3. Employees must complete onboarding before they can be paid
  4. Check for specific blockers in the onboarding status response

API Version Compatibility​

Unexpected response formats or missing fields in API responses.

Cause: Gusto uses date-based API versioning, and different versions have different response formats.

Solution:

  1. This connector uses API version v2026-02-01 (set in the X-Gusto-API-Version header)
  2. Ensure you're expecting response formats from this version
  3. Check the Gusto API Changelog for version-specific changes
  4. When upgrading API versions, review the Version Upgrade Guide
  5. Test thoroughly with the new version before deploying