You can authenticate against our authentication service by sending a specially crafted URL from your third party application. In order to access this service, you must have two things:

• an unique API key which is created by the Policy Center and supplied as part of your software subscription agreement;
• a Policy Center web services user account and password;

Briefly speaking there are two authentication steps you need to pass before you can start using all other REST services:

• STEP I (system.connect) : Connect to get anonymous session ID;
• STEP II (user.login): Connect to get registered user session ID;

Keep reading to find more information about how to authenticate against our authentication service.

**This authentication setup is NOT applicable to the Iron Mountain Data Centers portal**

Authentication Step I (system.connect)

 Initially you should log in to our authentication service as an anonymous user with a connection URL using method system.connect. The authentication service will send you back XML respond with generated for you anonymous session ID.

Here is example of connection URL:

https://demo.fontisinternational.com/services/rest?method=system.connect&nonce=eD24gpbc7u&domain_name=yourdomainname.com
&domain_time_stamp=1271162182&hash=3cf7755e7
cdc2b35afa2b40c145619d1bb5e80d86897c502ec4b9fe3fd0e8827

Where:

• method - required argument which is always equal to 'system.connect' for STEP I and 'user.login' for STEP II;
• nonce - required argument which is using for security reason. It is actually any random value, but take in account that you should always generate unique nonce, otherwise the authentication service will respond with error;
• domain_name - required argument which is using for security reason. It is indicates the domain name you were assigned by the Policy Center (supplied as part of your software subscription agreement);
• domain_time_stamp - required argument which is using for security reason. You should use Unix time (the number of seconds since 00:00:00 UTC on January 1, 1970). Also take in account that each authentication request has 30 seconds to send its request, otherwise the authentication service will respond with an error;
• hash - for security reason you always need to include the "hash" argument which is keyed hash value generated using the HMAC method, where the hashing algorithm is 'sha256', and the data is string comprised of 'domain_time_stamp'' +';' +'domain_name' +';' + 'nonce' +';' +'method' and key is your API key (provided by the Policy Center). Here is PHP example: $hash = hash_hmac('sha256', $domain_time_stamp.';'.$domain_name.';'. $nonce.';'.'system.connect', $private_api_key, 0));

Once you get response from our Authentication Service it will look like this:

success

     gcjmr7p7ugv15p24qla2c7ump2
                       0
                       84.201.227.138
                                anonymous user
                                0

All you need is to grab value (indicated in bold). The session id is required for next authentication step. If you did something wrong you will get error XML response from our Authentication Service with an error message inside:

    error
           error
           Invalid API key.

or:

   error
           error
           Token has expired.

or:

   error
          error
          Token has been used previously for a request. Re-try with another nonce key.

Authentication Step II (user.login)

Once you have connected as an anonymous user and have received an anonymous session id, you will need to login with a valid Policy Center service account using method user.login. Once authenticated, the service will send you back registered user session id.

Here is example of connection URL for user login:

https://demo.fontisinternational.com/services/rest?method=system.connect&nonce=eD24gpbc7u&domain_name=yourdomainname.com
&domain_time_stamp=1271162182&hash=3cf7755e7cdc2b35afa2b40c145619d1bb5e80d86897c502ec4b9fe3fd0e8827

Where:

• method - always equal to 'user.login' for STEP II;
• sessid - valid anonymous session id. You should use exactly the same session id that you grabbed during STEP I (system.connect), otherwise the authentication service will respond with an error;
• username - use the service account user name, provided by the Policy Center for the argument;
• password - use service account password, provided by the Policy Center for the argument;

Once you get response from our Authentication Service it will look like this:

success
          t3hfgib6k2nnhbkgt4keruos26
                   15
                    serviceuser
                    dd382052ffc8d14aaec24adedafc5f3f
                    serviceuser@fontisinternational.com
                    0
                    0
                    0
                    1353673334
                    1359024904
                    1359028253
                    1
                    0
                    serviceuser@fontisinternational.com
                    a:1:{s:13:"form_build_id";s:37:"form-bfb4f6519e6f5c3162078e928ad3737c";}
                    Europe/London
                    0
                    form-bfb4f6519e6f5c3162078e928ad3737c
                              authenticated user
                              service user

Again as for STEP I all you need is to grab value (indicated in bold). This is registered user session id, once you have it you will never need to build HASH anymore. Just use HTTP Cookies to submit the session id for all further REST server requests. Here is also additional list of XML responses you could get in case of any errors:

error
error
Invalid sessid.

or:

error
Wrong username or password.

or:

error
error
Access denied.

If you have any kind of difficulties with authenticating against our authentication service please contact our support. All you need to do is log-in to your Policy Center application instance via web browser and click on the help link in the top right corner of the screen.