Refresh an access token

Once your app has a users's OAuth token, you should ensure it's unexpired before using it.

Check validity

As you recall, the access code response includes both a timestamp when it was created, and an expiry time, in seconds. So you can know in advance of using an access code if you might need to refresh it first.


Refreshing an access token is easy and uses the same endpoint you used to create it: api/oauth/token. (Remember to specify the same sandbox or production server used when creating the token.)

For example, a test query for an app targeting our US servers uses this endpoint:


Example request

When refreshing a token, specify refresh_token as the grant_type and instead of including an authorization code, include the refresh_token you received with the access token.

curl -X "POST" "" \
  -H 'Content-Type: application/json' \
  -d $'{
  "grant_type": "refresh_token",
  "client_id": "83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394",
  "client_secret": "5305x72xxx6xx7xx4848xxxxx040x4xx4xx965xx566x662xxxxx6x7xxx5x730x",
  "refresh_token": "xxxx4x98xxxx7x03xxxxxx73x95x2514x0xx2x9xx15882xx7947496376x343x9",
  "redirect_uri": ""

Example response

As long as

  • you're requesting a refresh token from the same server that gave you the access token; and
  • the user hasn't revoked their authorization of your application

you'll get back a response that includes a new OAuth access token.

The response parameters are the same as you receive when getting the user's first access token, but will have an updated created_at timestamp and a new refresh_token.

200 OK
  "oauth": {
    "access_token": "96x5x67x09168xx64x4x8xx5xx541xxxxx38x10071xx1xxx24x66x0xxxxxxx74",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "xxxx4x98xxxx7x03xxxxxx73x95x2514x0xx2x9xx15882xx7947496376x343x9",
    "scope": "catalog:read",
    "created_at": "2021-06-16T14:57:21.000Z",
    "resource_owner": {
      "id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx",
      "type": "Practitioner"

The refresh_token you used to make this call doesn't expire, so you don't need to replace the one you're using with this new one. But you can if you want to, the new one is also valid and has no expiration.