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"
}
Updated about 1 month ago