OAuth 2.0

OAuth 2.0 allows Expiration Reminder users to authorise third party apps to access their data without sharing their Expiration Reminder login details. Instead, an app will have one access token and one refresh token for each authorised Expiration Reminder user account.

The Expiration Reminder API implements OAuth 2.0 Draft 22.

How OAuth 2.0 works

The App developer registers a new app at the Expiration Reminder Apps Dashboard to obtain an OAuth Client ID and Secret. The Client ID and Secret are unique to each App.

When a user initiates authorization of an App to access their Expiration Reminder account, the App sends the user to the Expiration Reminder's OAuth Authorization Endpoint with the Client ID and some other parameters in the URL. The User is prompted to log into Expiration Reminder and will be shown a screen allowing them to allow or deny access. If the user allows access, Expiration Reminder will redirect the User back to the App using the Redirect URI which was either provided when the developer registered the app or included in the URL which sent the user to the Authorization Endpoint. The call to the Redirect URI will include an authorization token if the access request was approved.

There are various strategies which can be used to retrieve the authorization token from this redirection. For iOS Apps the most likely strategy is to register a custom URL scheme and set a URL using this scheme as the Redirect URI. Web apps will redirect the user to a URL on their site.

Once the App has the Authorization Token it must exchange this for Access and Refresh Tokens. This is done out of band.

The App makes an HTTP request to the Expiration Reminder OAuth Token Endpoint including the Client ID, Secret and the Authorization Token amongst other parameters. In return the App will receive an Access Token and a Refresh Token.

The Access Token is included in an HTTP header on each API request. The Refresh Token is used to request a new Access Token when the Access Token expires.

The Authorization Request

To link a user account to the app, the app must send the user to Expiration Reminder's OAuth Authorization Endpoint https://app.expirationreminder.net/oauth/authorize with the following URL parameters:

An example is shown below:

https://app.expirationreminder.net/oauth/authorize?redirect_uri=https%3A%2F%2Fcode.google.com%2Foauthplayground%2F&response_type=code
    &client_id=957F9E3F-2B80-45FD-9BAC-0214B1868DCA&state=xyz

If approved, the app will redirect to the Redirect URI including the Authorization code and the optional state parameters:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=3F58A2FE-DC09-45B1-B6CC-B6D10FB9FA78&state=xyz

The Access Token Request

The App must exchange the Authorization Token for an Access Token and a Refresh Token. To do this, the app makes an HTTP GET to the Expiration Reminder Token Endpoint https://api.expirationreminder.net/oauth/token using the Client ID and Client Secret as query string paramaters:

For example:

Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code&client_id=957F9E3F-2B80-45FD-9BAC-0214B1868DCA
&client_secret=y9A2WxLo6g4DTr53CnJs87HtPw98Yep5E7ZaSm50
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

If successful, the server will return a JSON response containing the access token and refresh token:

{
 "access_token":"A128F963-70F5-4549-8A92-E3E333240217",
 "token_type":"bearer",
 "expires_in":3600,
 "refresh_token":"93A5DF1A-1EFD-4983-A534-9E4E5AFBEE0F",
 "scoe":"",
 "state":xyz
}

Using the Access Token

On each API request, the access token must be presented in an HTTP header with the following format:

Authorization: Bearer TOKEN

Refreshing the Access Token

Refresh tokens do not expire and may be used at any time to retrive a new access token. This means it may be most convenient to refresh the access token on the next use after expiry. Some client libraries will handle this automatically.

To refresh an access token, the app makes an HTTP GET to the Expiration Reminder Token Endpoint https://api.expirationreminder.net/oauth/token using the Client ID and Client Secret as query string paramaters:

For example:

Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

If successful, the server will return a JSON response containing the new access token:

<
{
 "access_token":"A128F963-70F5-4549-8A92-E3E333240217",
 "token_type":"bearer",
 "expires_in":3600,
 "refresh_token":"93A5DF1A-1EFD-4983-A534-9E4E5AFBEE0F",
 "scoe":"",
 "state":xyz
}

Client Libraries