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 will not expire until you use the newly obtained access_token. If an error occurred while processing the response on your end, you can retry the request with the old refresh_token. After the first use of the new access_token, only the new refresh_token will be valid.