Authentication

Gusto Embedded has two types of tokens that are used throughout development: organization level tokens (api_token) and company level tokens (access_token,refresh_token). You will need to securely manage and store all access tokens, api tokens, and refresh tokens in your database.

The organization level token is available when you create an organization and application in the developer portal.

Retrieving Access Tokens

Using the api_token you can create a new partner managed company. In the header of the request you will include the api_token using an Authorization HTTP header with the token scheme.

Content-Type: application/json
Authorization: Token bbb286ff1a4fe6b84742b0d49b8d0d65bd0208d27d3d50333591df71

After creation of a partner managed company, you will receive an access_token, refresh_token, and the uuid of the created company to make subsequent API calls on behalf of the company.

{
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
  "company_uuid": "d525dd21-ba6e-482c-be15-c2c7237f1364"
}

Refreshing Access Tokens

This access token expires 2 hours after they are issued. If an access token is expired you will receive 401 Unauthorized errors. To refresh the access token, you will need the client_id, client_secret, and redirect_uri from the application you created in the developer portal as well as your refresh_token. A refresh_token does not expire and can be used to refresh indefinitely. However, our refresh process has a built-in mechanism for you to rotate refresh_token if you choose to.

To refresh your access_token use the POST oauth/token endpoint and include the refresh_token and "grant_type" : “refresh_token” in the request body.

The client_secret cannot be passed via API request URLs. Attempting to include the client_secret in the request URL will result in a 400 Bad Request error.

curl --location --request POST 'https://api.gusto-demo.com/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token {{API_TOKEN}}' \
--data-raw '{
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "redirect_uri": "https://localhost:3000",
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
  "grant_type": "refresh_token"
}'

import fetch from 'node-fetch';

const url = 'https://api.gusto-demo.com/oauth/token`;
const options = {
  method: 'POST',
  headers: {
    accept:'application/json', 
    'content-type': 'application/json',
    'Authorization': 'Token {{API_TOKEN}}'},
  body: JSON.stringify({
    'client_id': '{{client_id}}',
    'client_secret': '{{client_secret}}',
    'redirect_uri': 'https://localhost:3000',
    'refresh_token': '8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1',
    'grant_type': 'refresh_token'
    })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

The corresponding response will include a new access_token and refresh_token.

{  
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",  
  "token_type": "bearer",  
  "expires_in": 7200,  
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"  
}