The IRIS API2 is a RESTful JSON API. The API can be called using standard HTTP requests with standard Authorization headers and standard HTTP response codes.


The base URL that will be used for the API is:


  http://your-dce-server/iris/api2/api



All methods will be tagged onto the end of this base URL. Some examples:


  GET http://your-dce-server/iris/api2/api/views

  GET http://your-dce-server/iris/api2/api/views/ABC001

  POST http://your-dce-server/iris/api2/api/users/joesoap



These will get a list of all customers, get a specific customer and update a user respectively.


Authorization


The web service should be secured, and in order to that that you need to create an API user (any username). The user must have IRIS-ADMIN rights. You can use the standard HTTP Authorization header, as almost all clients should support this header:


 

 Authorization: Basic YXBpdXNlcjphcGlwYXNz



For example in curl, you can just do:


  curl --user api_user:api_passwd …



If you really want to encode the string yourself, you're welcome to do it though as follows:


  perl -e "use MIME::Base64; print 'Basic '.encode_base64('apiuser:apipass');"

  Basic YXBpdXNlcjphcGlwYXNz


and supply the Authorization header:


  curl --header "Authorization: Basic YXBpdXNlcjphcGlwYXNz" …



Authorization with Cookie


If your clients supports cookies, you may use the cookie to avoid subsequent re-authentication. The API will always send the cookie in the header as follows:


  Set-Cookie:sessiontoken=1e3e625236f1a78c220be494ed49a98b; path=/; expires=Mon, 02-Dec-2013 21:04:10 GMT


You can simply set the cookie on your outgoing requests and it should add the following to your header:

  

Cookie: sessiontoken=1e3e625236f1a78c220be494ed49a98b


In curl it would be:


  curl --cookie 'sessiontoken=1e3e625236f1a78c220be494ed49a98b'  …


A typical request


Say, we would like to create a user. We would do the following:

  curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \

     -d'{"email":"joesoap@suds.co.za","passwd":"123456","name":"Joe Test User","username":"joesoap"}' \

     http://your-dce-server/iris/api2/api/users


Different implementations use different syntax, but they all supper the standard HTTP authorisation.



Single Sign-On (SSO) Authorisation


SSO users can be authorised using the API as well. The client portal will need to authenticate using the above method (using the API user) and call the getSSOSession method. This method will return a valid session that can be passed onto the users browser and let the user use Iris as if he were logged in already.


For SSO users, there is no actual users in Iris. Instead you can log in with a specific customer code which becomes your SSO username. This means the user is restricted to that specific customer code. This can also be done with customer group filters, by logging in with the customer group name. The use could also specify particular role, which the user will have after the authentication.


So, let's look at an example where user joe logs into his customer portal and tries to use Iris. The user joe is linked internally to some CRM ID abc001. This code is used to link Iris to the CRM system using the customer code field.  Joe clicks on the "IRIS" button in the portal. The portal now does a background call to the Iris system to get a new auth session for Joe:


  curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \

     http://your-dce-server/iris/api2/api/getSSOSession?code=abc001


Iris will return something like (note: the parameter name is <b>sessionid</b>):

  {

    "sessiontoken": "1e3e625236f1a78c220be494ed49a98b",

    "loginurl":  "http://your-dce-server/iris/home?sessionid=1e3e625236f1a78c220be494ed49a98b"

  }


And the user will be logged in as an SSO user that has filtered access to the customer code "abc001". If you wish to hide the menu and nav controls you can use whitelabel=1 to hide these for use in an iFrame or something similar.


You can use the loginurl, or any URL that you want the customer to access. This is the "landing page". As long as the IRIS-CUSTOMER access has access to this page you can send the user here. If you want to access a page that requires a different access level, you'll need to set the role for the user as follows when you request the token:

  http://your-dce-server/iris/api2/api/getSSOSession?code=abc001&roles=IRIS-USER


It is also possible to use a group, instead of a customer - WARNING: This may be deprecated in the future though! - as follows:

  http://your-dce-server/iris/api2/api/getSSOSession?groupname=MyGroup


Once you have the sessionid, you can simply tack the sessionid onto virtually any URL in Iris and it will work provided that the required access level is met. For example:

  http://your-dce-server/iris/reports/fortigates/list?sessionid=1e3e625236f1a78c220be494ed49a98b


If you which to hide the menu navigation and footers, you can use the whitelabel parameter. This makes Iris suitable to include in another portal. You will need to add your own navigations to different Iris pages though, if needed.


  http://your-dce-server/iris/reports/fortigates/list?sessionid=1e3e625236f1a78c220be494ed49a98b&whitelabel=1


Being Polite

To reduce the load the default value of data that gets retrieved is set to 1000. This can be changed by either setting the increase ?count=XXX or traverse the pages with ?page=X. For example:

  Retrieving 300 customers will look as follow:

    http://your-dce-server/iris/api2/api/customers?count=300


  Or you can view the second page of customers:

    http://your-dce-server/iris/api2/api/customers?page=2


Methods


API Methods for version 1.2 and later