Authentication

Safety First!

Due to the sensitive nature of payroll, all potential integrations must be vetted and approved by Gusto.

To ensure you receive initial approval prior to investing in your build, please sign up for a Gusto Developer Account, fill out the Production Pre-Approval application and await a response from Gusto's Partnerships team.

During development, all API calls must be made to api.gusto-demo.com.

After passing QA, Gusto will issue your production credentials via the Developer Portal. After receiving your production credentials, you can start making calls to our production environment via api.gusto.com.

❗️

Please Note

Gusto is unable to provide production test accounts. All testing, both pre- and post-launch, must take place in our demo environment.

Authentication

The Gusto App Integrations API has two types of tokens that are used throughout development: organization level API tokens (api_token), provided via the Developer Portal, and company level tokens (access_token, refresh_token), provided via the OAuth2 process. You will need to securely manage and store all access tokens, api tokens, and refresh tokens in your database.

Token Management Recommendations

Access/refresh token pairs are specific to a user and company. The following gusto_auth_tokens table definition is an example of how Gusto tokens can be stored.

• company_uuid is the Gusto company UUID. This column could also be a foreign key to your own companies table that contains a gusto_company_uuid column
• access_token_expiration is the expires_in response field, which is the expiration time in seconds of the newly generated access_token
  • The expiration time is 7200 seconds or 2 hours.
  • To be safe, the access_token_expiration can be set to (expires_in- 60) from when the response is received.
  • This field can be used to proactively refresh tokens instead of always waiting for a 401 response to trigger a refresh.

Care should be taken to avoid token refresh race conditions. It is recommended to have unique constraints and when refreshing tokens, lock the associated row.

Example refresh steps:

1. An access token needs to be refreshed. We know this because the access_token_expirationis less than current time or an HTTP status of 401 is received from a Gust API request
2. Lock the gusto_auth_tokensrow for the associated company_uuid
3. Refresh the access token as detailed here
4. Update the gusto_auth_tokensrow with the new access and refresh tokens. The access_token_expirationshould also be updated to (expires_in- 60) seconds from the current time.
5. Unlock the row
6. Use the new access_token for Gusto API requests
7. All concurrent processes should use the latest access_token