App uses a refresh token to obtain a new access token

The app can use the expires_in field from the authorization response (see step 3) to determine when its access token will expire. After an access token expires, it may be possible to request an updated token without user intervention, if the app asked for a refresh token via the offline_access scope (see SMART on FHIR Access Scopes for details) and the EHR supplied a refresh_token in the authorization response. To obtain a new access token, the app issues an HTTP POST to the EHR authorization server's token URL, with content-type application/x-www-form-urlencoded

For public apps, authentication is not possible (and thus not required). For confidential apps, an Authorization header using HTTP Basic authentication is required, where the username is the app's client_id and the password is the app's client_secret (see example).

The following request parameters are defined:

Parameters
`grant_type`	required	Fixed value: `refresh_token`.
`refresh_token`	required	The refresh token from a prior authorization response
`scope`	optional	The scopes of access requested. If present, this value must be a strict sub-set of the scopes granted in the original launch (no new permissions can be obtained at refresh time). A missing value indicates a request for the same scopes granted in the original launch.

The response is a JSON object containing a new access token, with the following claims:

JSON Object property name
`access_token`	required	New access token issued by the authorization server.
`token_type`	required	Fixed value: bearer
`expires_in`	required	The lifetime in seconds of the access token. For example, the value 3600 denotes that the access token will expire in one hour from the time the response was generated.
`scope`	required	Scope of access authorized. Note that this will be the same as the scope of the original access token, and it can be different from the scopes requested by the app.
`refresh_token`	optional	The refresh token issued by the authorization server. If present, the app should discard any previosu `refresh_token` associated with this launch, replacing it with this new value.

In addition, if the app was launched from within a patient context, parameters to communicate the context values MAY BE included. For example, a parameter like "patient": "123" would indicate the FHIR resource https://[fhir-base]/Patient/123. Other context parameters may also be available. For full details see SMART launch context parameters.

For example

If the EHR supports refresh tokens, an app may be able to replace an expired access token programatically, without user interaction:

Request

POST /token HTTP/1.1
Host: ehr
Authorization: Basic bXktYXBwOm15LWFwcC1zZWNyZXQtMTIz
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=a47txjiipgxkvohibvsm

Response

{
  "access_token": "m7rt6i7s9nuxkjvi8vsx",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "patient/Observation.read patient/Patient.read",
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}