StatPro Revolution Web API


Authorization using OAuth2


Batch applications

Batch applications are those that typically do not display a user interface, especially not at runtime when access to the Revolution Web API is required. Such applications are designed to run unattended (e.g. overnight).

To support such applications, Data Feed User accounts are used. StatPro Client Services will create a "batch authorization" at setup time (as opposed to runtime) that allows a specific Batch application access to a Data Feed User's data at runtime. The batch authorization is represented externally by a special type of password, known as an application-specific password (or ASP). The Batch application is then set up with the Data Feed User's email address and ASP, which it uses at runtime (via the OAuth 2.0 Resource Owner Password flow) to get an access token.

For more information about this process, and about Data Feed Users in general, please see Using Data Feed User accounts for batch access.

Whether a Batch application is considered to be confidential or not (with respect to OAuth 2.0) depends on where it runs, and how well it guards its client secret. Batch applications also have a duty to keep Data Feed User credentials (email address and application-specific password) as confidentially as possible.


Workflow

The following subsections detail how a registered Batch application named "BA1" gets an access token from the OAuth2 Server, and then uses that access token to request user data from the Web API.

The steps are:-

  1. StatPro Client Services create a batch authorization for a Data Feed User (DFU)
  2. Tenancy owners specify the batch authorization's email address and application-specific password to the client application
  3. Client application swaps the DFU email address and application-specific password for an access token
  4. Client application issues requests to the Web API using an access token
  5. Client application gets a new access token

For steps 3 and 5, a firm understanding of section '4.3. Resource Owner Password Credentials Grant' of RFC 6749 is required. (Note that the wording of this section of RFC 6749 assumes that the password in question is a user's real / personal password, and so recommends that only highly privileged applications support the Resource Owner Password Credentials Grant, aka Resource Owner Password flow. However, by using an application-specific password, these concerns are mitigated for StatPro Revolution Batch applications.)


Step 1. StatPro Client Services create a batch authorization for a Data Feed User (DFU)

Tenancy owners (aka local administrators) should contact StatPro Client Services and ask them to perform this step.

For more details, please see this section.


Step 2. Tenancy owners specify the batch authorization's email address and application-specific password to the client application

Armed with the DFU's email address and application-specific password obtained in step 1 above, a tenancy owner should be directed to specify these credentials to application "BA1", so that the application can use them at runtime. How this is done is entirely dependent on how "BA1" is written, and what its setup time user interface is.

Batch applications must store these user credentials as confidentially as possible.


Step 3. Client application swaps the DFU email address and application-specific password for an access token

At runtime, the client application makes a POST request to the OAuth2 Server's Token endpoint (https://revapiaccess.statpro.com/OAuth2/Token) to swap the username (= email address) and password (= application-specific password) for an access token, using the OAuth 2.0 Resource Owner Password flow.

The rules of this request are described in section '4.3.2. Access Token Request' of RFC 6749.

Note that the scope form parameter is REQUIRED by the OAuth2 Server.

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

Notes:-

  1. The client identifier is NOT included in the entity body of the request.
  2. The client identifier is the application's public identifier, and is specified when registering the application.
  3. The client secret is provided to the application's administrator after the application has been successfully registered.

Example:-

POST https://revapiaccess.statpro.com/OAuth2/Token HTTP/1.1
Host: revapiaccess.statpro.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=datafeed.3d41218c%40noreply-statpro.com&password=4c%7Bxhp%3AXd09XG1Iq(GGQ%2FV8tkLko%7ByW(%3AWF%3ACFJudi-E%7Cp3%3Fv)%3DAJm%7C%3AFh%2B13%2BMg&scope=RevolutionWebApi


The response to the access token request is described by sections '4.3.3. Access Token Response', '5.1. Successful Response' and '5.2. Error Response' of RFC 6749.

For a successful response:-

  • it is guaranteed that the access token is base64-encoded; this has implications when requesting resources from the Web API;
  • the OAuth2 Server won't include a refresh token;
  • the lifetime of the access token is currently set at 3600 seconds (an hour), but this is an implementation detail and is subject to change;
  • the token type is currently set to be "Bearer";
  • the server will always indicate the scope of the issued access token (i.e. what Resource Servers are accessible); this is a space-delimited list, although currently it will only be set to "RevolutionWebApi";
  • the server always augments the JSON in the entity body with the user's external identifier (which uniquely identifies the user within the Revolution system) and the user's display name, using members user_id and user_name respectively. See below for an example.

For an error, the response is as per '5.2. Error Response' except that:-

  • error_uri is not currently set;
  • if an internal server error occurred, the response status is 500 and the error code is set to "server_error" (a non-standard error code in the context of this response);
  • if the server denied access for reasons not covered by the other error codes, the error code is set to "access_denied" (a non-standard error code in the context of this response).

Example of a successful response:-

{
    "access_token": "<base64-encoded access token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "RevolutionWebApi",
    "user_id": "4289ee5d82e3d8fb48ce4048e82344bc44ced59122a34db287c2457379aeb3e9",
    "user_name": "Web API Data Feed"
}


Step 4. Client application issues requests to the Web API using an access token

Armed with the base64-encoded access token via the preceding step, the client app issues a request to the Revolution Web API (described elsewhere).

For each and every request to the Web API, add an Authorization header in this format:-

Authorization: Bearer <accessToken>

The access token must not be base64-encoded by the client application, because it is already base64-encoded.

The OAuth 2.0 Bearer Token Usage specification identifies three different methods of providing a bearer access token. The StatPro Revolution Web API supports only one - the Authorization header (aka Authorization Request Header Field) method.

A successful response should result in the requested resource representation being returned.

An unsuccessful response is described in section '3. The WWW-Authenticate Response Header Field' of RFC 6750. See sub-section '3.1. Error Codes' for how the Web API indicates that an access token is invalid or has expired. Example:-

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="StatPro Revolution Web API", error="invalid_token", error_description="The access token is invalid."

Note that a client application can use the date/time of receiving an access token combined with the indicated lifetime of the access token to predict (roughly) when it will expire, rather than waiting for the Web API to tell it so. (A well-behaved client application will only ask the OAuth2 Server for another access token when the current one has expired, or when expiry is imminent - e.g. within the next minute.)


Step 5. Client application gets a new access token

If an access token is used successfully (say for an hour), but then the Web API suddenly responds with a 401 status and an error of "invalid_token", for example:-

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="StatPro Revolution Web API", error="invalid_token", error_description="The access token is invalid."

then the access token has expired. In this case the client application can request another by simply re-submitting the DFU's email address and ASP, as described in step 3.


Tenancy information

Batch applications can get information about the tenancy that an access token targets (which will be the Data Feed User's primary tenancy by definition). This advanced topic is covered on the Tenancy selection page.


Last updated: January 2017


To Top