Introduction

When using any of the Igloo APIs to develop your integration or application, you must first be authenticated with you’re the digital workplace you are developing on. To authenticate means that one entity has proven its identity to the other party. This proves that you are who you are, serving as an identification card. 

Following are the steps that need to be followed to ensure that you are successful authenticating:

1. Once you have signed up for the Developer Program (Developer Program sign up), you will receive two important credentials, an Igloo App ID (API Key) and Igloo App Password (API Password). Other pieces of information needed:
   1. Username - The email address of the user you are authenticating with. This user must be a member of the site and have proper authorization to make API calls.
   2. Password – The password of the user.
   3. Community – The URL of the community (your Digital Workplace) you are authenticating against.
   4. API Version – The version of API you are using to authenticate, in this case, it is V1 API, so the value is 1 (integer)
2. When all the pieces of information have been obtained, you are ready to make the API call to authenticate. Reference for all Igloo API's. Specifically we are going to use the API listed under Session: /.api/api.svc/session/create
3. The above API call requires all the pieces of information that are listed in Step 1 as Query Parameters. Following is a sample call written in Python to show the structure used. This example should serve as reference when making this API call in your language of choice.

def session_create(self, app_id, app_password, username, password):
    """
    Creates a session with your IGLOO Digital Workplace - V1
    :return: Token Id - used to create subsequent API calls
    """
    url = "{}/.api/api.svc/session/create".format(self.url)
    params = {
        "appId": app_id,
        "appPass": app_password,
        "username": username,
        "password": password,
        "community": "https://yourdigitalworkplaceurl.ca/",
        "apiversion": 1
    }
    try:
        print(url)
        request = requests.post(url, params=params, headers={'accept': 'application/json'})

        response = request.json()
        print(response)
        return response['response']['sessionKey']

    except exceptions.HTTPError as err_http:
        print(str(err_http))
    except exceptions.ConnectionError as err_connection:
        print(str(err_connection))

What if I am authentication using the V2 API?

1. You still require the Igloo App ID (API Key) and Igloo App Password (API Password). The other pieces of information needed:
   1. Username - The email address of the user you are authenticating with. This user must be a member of the site and have proper authorization to make API calls.
   2. Password – The password of the user.
   3. Community – The URL of the community (your Digital Workplace) you are authenticating against.
   4. API Version – The version of API you are using to authenticate, in this case, it is V1 API, so the value is 1 (integer)
   5. Instance - representing the LDAP configuration instance in your community to use if you have multiple configurations. This is an optional parameter. Default value is 0
2. Once all the above pieces of information have been obtained, refer to the Igloo API’s. Specifically we are going to use the V2 API listed under Session: .api2/api/v{version}/session/create
3. Following is a sample call written in Python to show the structure used. This example should serve as reference when making this API call in your language of choice.

def session_create(self, app_id, app_password, username, password):
    """
    Creates a session with your IGLOO Digital Workplace - V2
    :return: Token Id - used to create subsequent API calls
    """

    url = "{}/.api2/api/v{}/session/create".format(self.url, self.api_version)
    
    # The Session Create V1 endpoint enables a user to get a session.
    # Compared to the unversioned endpoint,
    # this one supports authentication via LDAP and Igloo credentials.

    params = {
        "AppID": app_id,
        "AppPassword": app_password,
        "UserName": username,
        "UserPassword": password,
        "ApiVersion": 1,
        "Instance": 0

    }
    try:
        request = requests.post(url, data=params, headers={'accept': 'application/json'})
        response = request.json()
        print(response)
        return response["TokenId"]

    except exceptions.HTTPError as err_http:
        print(str(err_http))
    except exceptions.ConnectionError as err_connection:
        print(str(err_connection))

Conclusion

A Session Key or a Token ID is returned as a result of these API calls. Both confirm that you have been authenticated properly. For any subsequent API calls, you must pass this Session Key or the Token ID as a cookie in your header so that Igloo can validate and authenticate every single API call that is made in the future. Here is more information on how to make subsequent API calls.