For Integrators / Developers: Xplan API OAuth 2.0

[antony.nevis]

• Xplan OAuth Flow
• Step 1: Authorisation
• Step 2: Getting the Access Token
• Step 3: Access Protected Resource using Access Token
• Step 4: Refresh Token
• Access User Information
• HTML Examples
• HTML Form for Testing Step 1: Authorisation
• HTML Form for Testing Step 2: Getting the Access Token
• HTML Form for Testing Step 4: Refresh Token
• Errors

OAuth 2.0 is a protocol that lets your app request authorisation to private details in a user's Xplan account without getting their password.

You need to register your app with Iress before getting started. A registered app is assigned a unique App ID and Secret which will be used in the OAuth flow. The Secret should not be shared.

To register your App, please contact your Iress contact (e.g. Account Manager/Executive).

Xplan OAuth Flow

Step 1: Authorisation

Your web or mobile app should redirect users to the authorisation URI:

my_xplan_site/oauth2/auth

The following values should be passed as path parameters:

• "client_id" - App ID issued to you by Iress
• "response_type" - Use value "code"
• "redirect_uri" - URL to redirect back to

Here is an example:

my_xplan_site/oauth2/auth?client_id=my_app_id&response_type=code&redirect_uri=my_redirect_uri

If the user is not authenticated, the user will be challenged with Xplan Login page.

Once the user is successfully authenticated with Xplan, the following page will display:

My Test App is the app name you registered with us.

If the user clicks No, your app will not be authorised to access user resource and the user will be retained at the Xplan site.

If the user authorises your app by clicking Yes, Xplan will redirect the user to your specified "redirect_uri" with a temporary code in a "code" path parameter:

my_redirect_uri?code=js2qqmr6RTES9T7BfwFVJKflN2DyVfxnCzzBJq2l

The temporary code is called an authorisation code. Exchange this code for an access token in Step 2.

Note:

An authorisation code can only be exchanged once for an access token. If the authorisation code is exchanged more than once, the Xplan server will respond with a status of HTTP 400 Bad Request and an invalid_grant error.

 

Step 2: Getting the Access Token

You need to use the authorisation code from STEP 1 to exchange for an access token. 

The token URI is:

my_xplan_site/oauth2/token

The following values should be passed as HTML form data using POST method:

• "client_id" - App ID issued when you created your app
• "client_secret" - Issued when you created your app
• "redirect_uri" - URL to redirect back to
• "grant_type" - Use value "authorization_code"
• "code" - A temporary authorisation code received from Step 1 Authorisation

Below is an example in curl:

curl      --request POST ^
     --url
 ^
     --header "Content-Type: application/x-www-form-urlencoded" ^
     --data "client_id=my_app_id&client_secret=my_app_secret&redirect_uri=my_redirect_uri&grant_type=authorization_code&code=js2qqmr6RTES9T7BfwFVJKflN2DyVfxnCzzBJq2l" ^
     --include

 A successful response looks like below:

{
    "access_token": "aq0k0TPcQykKfxzCAIcIAC7Pk1GY1D5MlrpjG0AB",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "XPjyW0aylTgKGtV157nvpljTfEsZuZYkSlU2RjVE"
}

In the response above, you will find a valid access token that expires in 60 minutes, and a refresh token that can be used to exchange for a new access token and a new refresh token.

Note:

Only an access token can be used for accessing user resources. A refresh token cannot be used for accessing Xplan user resources.

An authorisation code can only be exchanged once for an access token. If the authorisation code is exchanged more than once, the Xplan server will response with HTTP 400 Bad Request and an error message below:

{
    error: "invalid_grant"
}

Step 3: Access Protected Resource using Access Token

In order to access Xplan API using OAuth access token, you need to add Authorization HTTP Header to your Xplan API request:

Authorization: bearer my_access_token

Below is an HTTP POST example to create a document using bearer token:

curl      --request POST ^
     --url "my_xplan_site/resourceful/docnote-v2" ^
     --header "Authorization: bearer aq0k0TPcQykKfxzCAIcIAC7Pk1GY1D5MlrpjG0AB" ^
     --header "Content-Type: application/json" ^
     --data "{\"subject\": \"this_is_a_test\",\"entity_ids\": [9, 10],\"mimetype\": \"text/html\", \"body\": {\"_type\": \"Binary\",\"_val\": \"PHA+ZmlsZXBhdGgvMDAxLm1wMzwvcD4=\"}}" ^
     --include

Step 4: Refresh Token

When an access token is expired or becomes invalid, you can use a refresh token to get a new access token. You can also use refresh token to get multiple access tokens. 

Note: A refresh token can be used only once, i.e. one a refresh token has been used it becomes invalid and a new refresh token will be required. Every time a access token is issued a new refresh token is also issued.

The token URI is:

my_xplan_site/oauth2/token‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The following values should be passed as HTML form data using POST method:

• "client_id" - App ID issued when you created your app
• "client_secret" - Issued when you created your app
• "redirect_uri" - URL to redirect back to
• "grant_type" - Use value "refresh_token"
• "refresh_token" - The refresh token

Below is an example in curl:

curl      --request POST ^
     --url "my_xplan_site/oauth2/token" ^
     --header "Content-Type: application/x-www-form-urlencoded" ^
     --data "client_id=my_app_id&client_secret=my_app_secret&redirect_uri=my_redirect_uri&grant_type=refresh_token&refresh_token=XPjyW0aylTgKGtV157nvpljTfEsZuZYkSlU2RjVE" ^
     --include‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

A successful response looks like below:

{
    "access_token": "lYNC18rjy068HlEvJq9O6MPV4h1qizqjgZbUqnx7",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "tDICH5JtA4sg5Uv0fb28TR6y3f3Dz6ql3Rwv6fPn"
}

In the response above, a new access token and a replacement of the refresh token are issued.

Access User Information

You may need to find out which user has just grant permissions to your App via OAuth workflow. The request below will return the user's ID:

Method:

GET my_xplan_site/resourceful/session/user‍‍‍‍‍

Sample Response:

{
    "locale": "AU",
    "entity_id": 2582,
    "role_name": "User",
    "last_login": {
        "_val": "2016-11-01T12:57:08.983333",
        "_type": "Date"
    }
}

Then you can get user(entity_id: 2582)'s information via the entity endpoint below:

my_xplan_site/resourceful/entity/user-v2‍/2582

HTML Examples

You can find some example HTML code here for testing OAuth interactions with Xplan API.

HTML Form for Testing Step 1: Authorisation

The HTML form below can be used for testing STEP 1: Authorisation:

<html>
<head>
</head>
<body>
    <form action="my_xplan_site/oauth2/auth" method="GET">
        <p>
            client_id: <input name="client_id" value="my_app_id" />
        </p>
        <p>
            response_type: <input name="response_type" value="code" />
        </p>
        <p>
            <input name="redirect_uri" value="my_redirect_uri" />
        </p>
        <button type="submit">Submit</button>
    </form>
</body>
</html>

Replace placeholders my_xplan_site, my_app_id, and my_redirect_uri with proper values. Save the code to a file named "STEP 1 Authorisation.html".

View the HTML in a browser, make sure the values are entered correctly and click Submit button.

HTML Form for Testing Step 2: Getting the Access Token

Besides the curl command, you can also use HTML form to test STEP 2: Getting the Access Token:

<html>
<head>
</head>
<body>
    <form action="my_xplan_site/oauth2/token" method="POST">
        <p>
            client_id: <input name="client_id" value="my_app_id" />
        </p>
        <p>
            client_secret: <input name="client_secret" value="my_app_secret" />
        </p>
        <p>
            redirect_uri: <input name="redirect_uri" value="my_redirect_uri" />
        </p>
        <p>
            grant_type: <input name="grant_type" value="authorization_code" />
        </p>
        <p>
            code: <input name="code" value="my_authorisation_code" />
        </p>
        <button type="submit">Submit</button>
    </form>
</body>
</html>

Replace placeholders my_xplan_site, my_app_id, my_app_secret, my_redirect_uri and my_authorisation_code with proper values. Save the code to a file named "STEP 2 Access Token.html".

View the HTML in a browser, make sure the values are entered correctly and click Submit button.

HTML Form for Testing Step 4: Refresh Token

Besides the curl command, you can also use HTML form to test Step 4: Refresh Token:

<html>
<head>
</head>
<body>
    <form action="my_xplan_site/oauth2/token" method="POST">
        <p>
            client_id: <input name="client_id" value="my_app_id" />
        </p>
        <p>
            client_secret: <input name="client_secret" value="my_app_secret" />
        </p>
        <p>
            redirect_uri: <input name="redirect_uri" value="my_redirect_uri" />
        </p>
        <p>
            grant_type: <input name="grant_type" value="refresh_token" />
        </p>
        <p>
            code: <input name="refresh_token" value="my_refresh_token" />
        </p>
        <button type="submit">Submit</button>
    </form>
</body>
</html>

Replace placeholders my_xplan_site, my_app_id, my_app_secret, my_redirect_uri and my_refresh_token with proper values. Save the code to a file named "STEP 4 Refresh Token.html".

View the HTML in a browser, make sure the values are entered correctly and click Submit button.

Errors

Possible errors from the POST /oauth2/token

invalid_request	The redirect URL passed in doesn't match the redirect URL stored in the API Key Portal. - Simple errors like preceding or following spaces in the URL textbox in the API Key Portal can cause this. While the URL passed in must start with the URL stored in the API Key Portal, they do not have to be 100% identical. Not all of the required parameters ['grant_type', 'client_id', 'client_secret'] were passed in.
invalid_client	The client_id or client_secret passed in is not the same as that stored in the API Key Portal. Note that it can take 1 hour for an Xplan site to refresh with the latest data in the API Key Portal. So if a secret is re-generated in the Portal it will not be available in the Xplan site immediately.
invalid_grant	The refresh token passed is is not correct.
unsupported_grant_type	the grant_type passed in was not authorization_code
server_error	An unexpected error occured