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 https://docs.gusto.com/v1/basics/authentication. 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)