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.