StatPro Revolution Web API


Authorization using OAuth2


Token revocation: Introduction

At runtime, users explicitly grant access for an interactive application (a Server-Side Web app or a Native app) to access their data via the Revolution Web API. An important part of the OAuth 2.0 Authorization Framework is that, later on, users are able to revoke such access. This is important if an application retains / persists a user's refresh token after the user stops using the application, and uses the refresh token again (to get an access token) when the user resumes application use.

A retained refresh token represents a previously-allowed (explicitly granted) authorization by the user for the application to access his/her Web API data. To negate this authorization, an application can allow the user to tell it to:-

  1. drop (forget about) the refresh token
  2. explicitly revoke the refresh token at the OAuth2 Server (and then have the application drop the refresh token).

Option 1 causes the underlying authorization - as stored on the OAuth2 Server - to be orphaned. It will be unobtainable, and will eventually be cleared from the server within a pre-determined number of days. This is the weaker option.

Option 2 causes the underlying authorization to be cleared immediately from the OAuth2 Server. This is the stronger option, and is recommended.

To support the second option, from October 2018 StatPro's OAuth2 Server has gained a token-revocation endpoint, which allows an interactive application to explicitly and programmatically revoke refresh tokens that have been issued to it. The endpoint address is:-

https://revapiaccess.statpro.com/OAuth2/RevokeToken

The rules that govern the protocol for refresh token revocation are described by RFC 7009.

Note: applications that do not retain and re-use refresh tokens from one user session to the next (such as StatPro's Web API Explorer web application), do not need to explicitly revoke refresh tokens.


How to revoke a refresh token

The rules of the token-revocation request are described in section '2.1. Revocation Request' of RFC 7009.

The OAuth2 Server REQUIRES that the client identifies itself via HTTP Basic Authentication for this request. E.g. include this request header:-

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

where the base64-encoded string is an encoding of:-

clientId + ":" + clientSecret

Example:-

POST https://revapiaccess.statpro.com/OAuth2/RevokeToken HTTP/1.1
Host: revapiaccess.statpro.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
token=3c5a821e-795e-44f7-abf4-ec0c0eb9bd30

Notes:-

  1. The value of parameter token must be a refresh token that was previously issued to the application.
  2. Parameter token_type_hint is ignored by the OAuth2 Server.


Responses from the token-revocation endpoint, and a word of warning about successful responses

The response to the token revocation request is described by section '2.2. Revocation Response' of RFC 7009.

In the case of error (e.g. missing or invalid Authorization header), the response status will typically be 400, 401 or 500, and may be accompanied by JSON response text with members error and error_description (the latter will be the more informative of the two).

Example error response (JSON):-

{"error":"invalid_client","error_description":"Invalid client identifier and/or client secret."}

The interesting case is when the response is successful - or at least when the OAuth2 Server responds with status 200. Perhaps surprisingly, this doesn't mean that the specified token was valid, and caused the underlying authorization to be removed from the server. This is because RFC 7009 states, for a revocation response:

The authorization server responds with HTTP status code 200 if the token has been revoked
successfully or if the client submitted an invalid token.

The OAuth2 Server's token-revocation endpoint will respond with an error under the following conditions:-

  • there is no POSTed request entity-body
  • the Content-Type header is missing or not set to application/x-www-form-urlencoded
  • the Authorization header is missing, invalid or contains invalid client credentials
  • the request entity-body does not contain parameter token, or its value is empty/whitespace
  • the identified client is a Batch application
  • the refresh token is valid, but was issued to a different client
  • the server suffered an unexpected error.

The OAuth2 Server's token-revocation endpoint will respond with 200 if there is no error condition (see above) and one of the following conditions applies:-

  • the specified token text is in an invalid format (for a refresh token)
  • the specified refresh token is unknown / could not be found
  • the specified refresh token is valid, and the refresh token and its associated underlying authorization were both removed from the server (i.e. success).

Because there is a 200 status response for both valid and invalid tokens, client applications should take care to specify the refresh token correctly. Additionally, they may wish to check that the refresh token was successfully revoked by attempting to use it post-revocation to get another access token (perhaps only in debug builds of the app).


Batch applications and negating outstanding authorizations

Batch applications aren't issued refresh tokens, and so do not use the new token-revocation endpoint.

To negate - or cancel - an outstanding batch authorization for a Data Feed User wrt a particular batch application, please contact StatPro's Client Services, identifying the application in question and the email address of the Data Feed User.

To negate a legacy batch authorization (i.e. for a normal user, not a Data Feed User), please email a request to webapisupport@statpro.com, identifying the application in question and the email address of the user.


Last updated: July 2018


To Top