Developer FAQs

OAuth & Integration Set Up

What is OAuth?

OAuth 2.0 is the industry-standard protocol for authorization and is required for any integration built to Gusto’s API.  Please review this example at The Developer Relations team at Gusto will issue your API Keys required for Authentication- your client id and secret-  as soon as you provide a redirect URI.

I got my API keys and I see the client id, secret, and an API Token. Where do I use this in Authentication?

The API Token is only used in Company Provisioning. It is not used in Authentication. More information on this below.

Does a user have to sign in anytime we need to make an api call on their behalf?

No, the redirect to a login page for the user to sign in is a one-time requirement. Once the user authorizes the integration, a refresh token is issued and this token can be leveraged in all future API calls. A refresh token only expires once it has been used but it can be exchanged for a new one.

I understand one user may be associated with multiple Gusto accounts. If I only ever want to sync one company per authenticated user (1:1 integration), do you have a recommendation for how we ask the user which company they would like to sync?

We recommend building a step for a user you detect to be associated with multiple accounts to select one of their Gusto accounts after authorizing (as part of integration setup). This video provides an example at ~4:30. You can also use this as an opportunity to clarify it is a 1:1 mapping and how the integration works.

Conversely, what if we want to allow the user to integrate multiple Gusto companies to their one account with us?

If a Gusto user has multiple accounts in Gusto and authorizes the integration, you can ping the current user (/me) endpoint for a list of companies associated with the authenticating user. We recommend storing these company IDs on your end to accurately and reliably sync information between Gusto and your system if/when a user authorizes multiple accounts.

Previous: Getting Started | Next: Company Provisioning (Creating a new Gusto account via the API)