At a glance
- Availability: Experimental (how to enable).
- Auth: OAuth 2.0.
- Connection: A user authorizes the connection in the provider’s consent screen.
- Docs: https://docs.gusto.com/app-integrations/docs/oauth2
Credentials
Set these per environment. See Connect an integration. With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.Setup
- Create a developer application: Sign up at https://dev.gusto.com and create an application. New apps start in the demo environment (api.gusto-demo.com) where you can create a free test company.
- Set the redirect URI: Add your deployment’s /api/auth/gusto/callback URL to the application’s redirect URIs.
- Set environment variables: Copy the application’s client_id and secret into GUSTO_CLIENT_ID and GUSTO_CLIENT_SECRET in your .env.
- Connect and verify: Complete the OAuth consent flow with a company admin account, then run Get Token Info to discover the company UUID and confirm access.
- Scopes/permissions are configured on the application in the Developer Portal, not passed in the authorize URL
- Access tokens expire after 2 hours; refresh tokens are single-use and rotate on every refresh
- Production access (api.gusto.com) requires Gusto’s app approval; until then use the demo environment
- Tools pin X-Gusto-API-Version: 2024-04-01; raise the default to adopt newer versions
Tools
| Tool | Access | Description |
|---|---|---|
| Get Token Info | Read | Get the resource (company) and scope associated with the current access token |
| Get Company | Read | Get a company’s profile, locations, and entity details |
| List Employees | Read | List employees of a company |
| Get Employee | Read | Get a single employee |
| List Payrolls | Read | List payrolls for a company |
| Get Payroll | Read | Get a single payroll with totals |
Example prompts
- List all active employees in my Gusto company with their departments and emails.
- Show my company’s processed Gusto payrolls for this quarter with their pay periods and totals.