Refresh Token Best Practices

Properly integrating a Refresh Token in your Authentication stream is essential to the health of your Application. Not using Refresh Tokens can result in headaches not only for Developers, but for End Users as well. Barring any credential or rights changes made by the user or agency, an application will want to consistently stay connected without having to login multiple times.

Best Practices

  1. Make sure you're using Refresh Tokens!
    • Frequently requesting an Access Token (without using a Refresh Token) is incredibly inefficient, resulting in more than twice the work necessary
    • One of the single biggest steps you can take is to implement the use of a Refresh Token in your authentication process
  2. Have a Refresh token work for you; use a Refresh Token whenever your app receives a 401 error
    • In your application code, include a trigger to automatically call to the Refresh Token URL whenever your app receives a 401 Unauthorized error
    • Calling the Refresh Token URL automatically will help your application stay connected to the API as long as possible and limit disruptions to users
  3. Consider re-sending the last failed call
    • If your application was making an API call and it failed, the data more than likely didn't make it across from one system to the other
    • If you've included logic in your application to use a Refresh token when it receives a 401 (see above), consider also including logic to re-send the call that failed prior to the 401 error

Quick Facts

  • Access Token Lifetime: 60 minutes
  • Refresh Token Lifetime: 1 week

A Successful Scenario

Let's say your application receives its first Access Token (good for 60 minutes) and Refresh Token (good for 1 week).

    RESPONSE
    {
        "access_token": "YOUR_ACCESS_TOKEN",
        "expires_in": 3600,
        "token_type": "Bearer",
        "scope": null,
        "refresh_token": "YOUR_REFRESH_TOKEN"
    }

NOTE: Store this Refresh Token as you'll need it later!

Your application calls the Get Stations endpoint immediately (1 minute) after the initial Access Token and Refresh Token are granted. Your application receives a 200 Success response and your app receives data for all of your stations.

    {
        "stations": [
            {
                "stationID": "123xx",
                "stationNumber": "1",
                "stationName": "Station 1",
                ...
            },
            {
                "stationID": "456xx",
                "stationNumber": "2",
                "stationName": "Station 2",
                ...
            }
        ]
    }

After an hour has passed, your application tries to call the Get Stations endpoint once again and a 401 Unauthorized error is returned. The Access Token is now invalid. This is OK!

Since it's been less than 7 days, the Refresh Token from your initial request is still good. Using the initial Refresh Token (that you stored), make a POST call to the Refresh Token URL to receive a brand new Access Token and brand new Refresh Token.

    Request
    POST https://data.emergencyreporting.com/refreshtoken/Token.php

    Body
    {
        "grant_type": "refresh_token",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "refresh_token": "YOUR_ORIGINAL_REFRESH_TOKEN"
    }

    Response
    {
        "access_token": "YOUR_NEW_ACCESS_TOKEN",
        "expires_in": 3600,
        "token_type": "Bearer",
        "scope": null,
        "refresh_token": "YOUR_NEW_REFRESH_TOKEN"
    }

Now that you've received a new Access Token and a new Refresh Token, the clock has been reset for both. You now have 1 hour to make calls using your New Access Token and your New Refresh Token will stay valid for 7 days.

A Best Practice is to include logic in your application to automatically invoke a Refresh Token Request anytime your application receives a 401 Unauthorized error.

Refresh Token Lifetime

Refresh Token Lifetime

Back to Top