Creating an invocation

The invocation object should be created as follows:

  • The URL of the invocation object should be set to the URL that browser is to load. The URL must be correctly formatted, for example, using URL encoding

  • Additional parameters may be added as separate invocation arguments. Each argument is a key/value pair with the format “key=value” and is case sensitive. Each argument must contain exactly one key/value pair. The following arguments are supported:

Argument name





This parameter is for web based authentication. It is set to the expected redirection URL when authentication has completed. When the browser is redirected to this URL it returns the complete URL in the invocation response including additional parameters added by the service such as access token. The browser closes after returning the invocation response.

In a typical OAuth scenario, this URL will also be a parameter within the request URL.



proxy direct

This parameter enables the invoking application to override the default mode of the browser (see below for more details about this).


This parameter is only supported in conjunction with redirect_intercept.

Invocation response

If the browser was invoked with the redirect_intercept argument, it will normally provide an invocation response as follows:

  • If the browser was redirected to the URL specified by redirect_intercept the invocation response URL is set to the URL redirected to, including any parameters added by the service (for example, access token). The status of the invocation response will be OK. The browser closes automatically in this scenario to return focus to the application.

  • If the user closes the browser before completing authentication the invocation is cancelled (the invocation response will have a status of CANCELLED).

  • The application must call Invocation.setResponseRequired(true) to get the invocation response.

It is the responsibility of the invoking application to parse the complete URL in the invocation response and extract parameters such as access token or to handle failure cases such as when the access token is not granted (the browser does not provide any indication of the actual success of the authentication other than the cancelled status).


Networks where default browser mode is “direct”

On most networks the browser is “cloud assisted” where actual rendering of the site is performed by a proxy server with the result delivered to the phone browser. The proxy server is able to execute the java script associated with most web authentication sites.

On some networks, due to legal restrictions, the browser does not use the proxy and renders the page using an embedded rendering engine that makes a direct internet connection. This rendering engine is generally not able to execute java script and hence will not support most web authentication sites.

The normal mode of the browser may be overridden for web based authentication by explicitly specifying it in the invocation using the mode parameter (that is, by adding “mode=proxy” as an invocation argument). It is permissible to add this argument even where the default mode is “proxy”. (The application can also explicitly specify “direct” mode if this is required for a particular scenario).

Redirect must be to an internet site

The mechanism cannot support authentication scenarios where the redirect URL is not an internet site accessible by the proxy server, such as where it is “localhost”.

Token accessibility

The mechanism cannot support authentication scenarios where the token is not returned as part of the redirect URL (for example, if it is encoded in other metadata in the response such as page title).

Last updated 9 October 2013

Back to top