Developer Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Refresh Your Bearer Token

Bearer tokens are short lived, so you’ll need to periodically get a new one in order to keep making calls to our API.

To refresh your bearer token, make the following request to the /auth/refresh endpoint. Assuming that you saved your refreshToken and it’s still valid, this operation will generate a new bearer token for you with a new bearer token expiration date. It will also generate a new refresh token for you with a new refresh token expiration date.

Request Paramaters
Parameter Type Usage Description
refresh_token string Required Current refresh token for your auth session
Response Body
   "success": true,
   "guid": "174fb2d3-22a6-4db5-b7cd-4c3c1d7d0e51",
   "token": "768556c0-bfbd-4c66-9774-328597b5e315",
   "tokenExpiration": "2018-04-02T21:39:12+00:00",
   "tokenLifetime": 3600,
   "refreshToken": "ba4664b4-0e5b-4e0d-9059-29cbf0142878",
   "refreshTokenExpiration": "2018-05-01T21:39:12+00:00"

Congratulations! You now have a new bearer token AND ALSO a new refresh token. Save your new bearer token and use it on all new API requests. Also save your new refresh token. You’ll need to use the new refresh token next time you perform the refresh operation. If you attempt to re-use the old refresh token again, the operation will fail.

The continuous workflow is like this:

  1. Get your original bearer token (previous step).
  2. When your bearer token expires, get a new bearer token AND a new refresh token (this step).
  3. When your bearer token expires, repeat #2. Keep doing this as long as you need.

You’ll notice that we give you both a tokenExpiration value, which is a datetime string, and a tokenLifetime value, which is an integer that represents the lifetime of the bearer token in seconds. It’s possible that the current time on our servers does not match the current time on your computer. If that is the case, then it is possible that the tokenExpiration value is not a reliable metric. Using this could cause your software to request an auth session refresh too soon, or too late.

Instead, generate your own future date by taking the current time and appending the value of tokenLifetime to it. This way, it doesn’t matter if your computer and server time do not match, since your time calculation will only ever be using the current time on your computer at any given moment. Using this example, if you get the current time, and using a date library, append 3600 seconds to the current time, you now have a date 1 hour in the future. This will 100% accurately represent when the bearer token expires.

We’ve seen client software incorrectly calculate time, which caused a feedback loop of auth session refresh. The client’s software was in an infinite loop of refresh many hundreds of times a minute.

You’ll see that the refresh token expires on the date specified in the refreshTokenExpiration variable that was returned to you. The expiration date will be much further in the future, but it will be finite. If you wait too long, you’ll have to start over and authenticate with your username and password again (continuous workflow step #1)