Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
Child pages
  • OAuth2 module - for Client Developers

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Creating and Managing Clients

See the REST Controller here

Obtaining Tokens

1. Authorization Code Grant Type


If the access token request is valid and authorized, the OAuth2 module will issue the access token and redirect to the redirection uri specified during client registration. The HTTP response to the client is exactly similar to those in Authorization Code grant type and Resource Owner Password Credentials grant type.


Refreshing Tokens

Once the validity period of access tokens is over, you will have to generate a new access token by using any of the above mentioned grant types or you can swap the expired access token with a new one by using the refresh token that was issued along with the access token.

You need to make a request to the Token Endpoint and include the refresh_token as the request parameter

URI : GET /ws/oauth/token

Request Parameters

access_tokenREQUIREDthe access token that has expired
refresh_tokenREQUIREDthe refresh_token that was issued along with the access token


Demo Request


Demo Response 

The response will include a JSON object containing the new access token, token type, expiry time and refresh token as shown in the Access Token Reponse for Authorization Code Grant Type.

Retrieving Protected Resources

If you try to access the OAuth2 protected resources without an access token, an 401 Unauthorized response code will be returned.

After obtaining an access token, it can be used to access the protected resources by including the access token in the Authorization Header or as an request parameter while requesting the protected resource.

The OAuth2 module will intercept this request and validate the token and allow access to the protected resource if the token passes validation 

Sample Request




Request HeaderValue
AuthorizationBearer fc49c67e-6932-4846-a4f9-e9a23822da1f