This document outlines the details for HTTP Basic Authentication to use with Iress Open API providing summary client level data for backend integratons.
Basic authentication should only be used for backend integrations.
If using basic authentication the Xplan site owner is responsible for creating and configuring the user account to be used for the integration (see Setting up an Xplan user for Iress Open section for further details on configuring the user account), and also passing these details securely to the integrator. The integrator and site owner need to consider the visibility of clients that a user will have. The user will count toward Xplan license limits. We recommend using OAuth2 as it is significantly more secure and usernames and passwords are not exposed.
There is no specific login endpoint for Iress Open. You can authenticate on any endpoint.
To authenticate you must supply both an Authorization header, and your app id (x-xplan-app-id). This is in addition to the x-forwarded-host header that specifies which site you want to use.
When you authenticate, a session is created in Xplan and a session cookie (XPLANID) is returned, in the Set-Cookie header.
All subsequent requests to Iress Open should pass this cookie in a Cookie header (note - this is different to Set-Cookie) along with the x-forwarded-host HTTP header, so that the existing session is reused for these requests.
If authentication fails, you will receive an HTTP 401 error.
Xplan decides the lifetime of this session token and may invalidate it at any time. This means that your client must, for each request, check for the possibility of an authentication failure at any time, and be ready to re-authenticate.
Note: Each time you successfully make a request passing username and password credentials in ‘Authorization: Basic ..’ you create a new session on our server. For performance reasons, your application should only pass these credentials when it does not have an existing session token. Session creation takes time, allocates resources, and may invalidate existing caches for your user. Passing session tokens via cookie is essential for efficient requests.
Setting up an Xplan user for Iress Open
Note: This only applies to basic authentication
To allow an integrator access to an Xplan site using basic authentication, the site owner will need to create a regular Xplan user and securely pass the credentials to the integrator.
The user should be carefully positioned with the group hierarchy to allow the integrator access the clients they should have access to.
The user capability set determines the functionality provided to the integrator. You should agree with the integrator the level of access that they need.
The integration user can be restricted to just API access by removing the ‘Standard Interface’ capability.
If the ‘Standard Interface’ capability is enabled for the user then the user account can be used to login to Xplan through the user interface and all capabilities granted to the user are available.