Xplan Integrations
cancel
Showing results for 
Search instead for 
Did you mean: 

Xplan API OAuth 2.0

Iress People

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 "https://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=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 one hour, and a refresh token that can be used to exchange for a new access token and a new refresh token.

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

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.

X
At Iress we are committed to ensuring that your experience using our community gets better. Did you find what you were looking for today?
We will use your feedback only for the purposes in which it was intended; to improve our products and services to you. At Iress, we always respect your privacy. To view our privacy notice, please visit our website