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.
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.
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:
client_id
(required) which is the Client ID obtained at Expiration Reminder App
Dashboard
response_type=code
(required)redirect_uri
(required unless supplied when registering) must be
url escaped
state
(optional) arbitrary parameters supplied by the app developer
to maintain their app's state
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 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:
grant_type=authorization_code
(required)client_id
(required) which is the Client ID obtained at Expiration Reminder App
Dashboard
client_secret
(required) which is the Client Secret obtained at Expiration Reminder App
Dashboard
code
(required) the authorization code received earlierredirect_uri
(required only if the redirect URI was specified when
making the Authorization request)
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
}
On each API request, the access token must be presented in an HTTP header with the following format:
Authorization: Bearer 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:
grant_type=refresh_token
(required)client_id
(required) which is the Client ID obtained at Expiration Reminder App
Dashboard
client_secret
(required) which is the Client Secret obtained at Expiration Reminder App
Dashboard
refresh_token
(required) the refresh token received earlierFor 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
}