Last Updated:
January 3, 2022
by
Muskan Purohit
| Version: 1
| 1,218 views
| 1 follower
members are following updates on this item.
To use Igloo’s extensive selection of APIs, you must authenticate. Authenticating to Igloo involves creating a session key that can then be used to make subsequent API calls. This article will walk you through how to do both these steps using Igloo’s v1 API.
To authenticate, you require the following information:
The App ID and App Password is provided to you when you register for the Igloo Developer Program.
Let’s get started!
This tutorial uses Node.js — although the principles apply to any modern language that can make RESTful calls. To follow along, you should be familiar with REST, JavaScript, Axios, and promises.
Axios is a promise-based HTTP client for the browser and Node.js. Axios makes it easier to send asynchronous HTTP requests to REST endpoints. Furthermore, because Axios is promise-based, we don’t have to create any promises of our own. Visit the Axios GitHub repository page for further information about using it.
Let’s look at an example of how to authenticate using the v1 API session create endpoint:
/.api/api.svc/session/create
The session/create endpoint takes the following parameters:
For Example:
const axios = require('axios').default;
var community = "COMMUNITY_DOMAIN"
var appId = "PERSONAL_APP_ID"
var appPass = "PERSONAL_APP_PASS
var username = "YOUR_IGLOO_USERNAME"
var password = "YOUR_IGLOO_PASSWORD”
Here we have imported Axios and have put each of the credentials into separate variables so we can access them later.
We can now create a function that will make the API call to create our session:
var url = community + "/.api/api.svc/session/create?appId=" + appId + "&appPass=" + appPass + "&username=" + username + "&password=" + password + "&community=" + community + "&apiversion=1" axios.post(url) .then(function(response) { var cookie = "iglooauth=" + response.data.response.sessionKey; console.log(response.data.response) }) .catch(function(error) { console.log(error); });
In the code snippet above, we first create the url variable to contain the hostname, API path of the session create API, and parameters required for the call.
Next, using Axios, we execute a POST call to send our request to the server. Axios will utilize a promise for this. Once the request is complete, we can store the response in a variable and, for the tutorial, output it to the terminal to view our session token.
We also have a .catch block which will trap any errors the function throws and display them for us.
The response should look similar to:
{ __type: 'Session:http://schemas.iglooplatform.com/Igloo.Old.Common', applicationId: ‘65b04709-3368-4b5d-a1b8-a70f850ff9de’, communityId: ‘ad594022-f127-480e-ae01-cb5a77785eb1’, userId: ‘a210da52-90a1-4b51-b851-3360cde5403f’, secretKey: ‘b63a0d8d-a8a7-4265-add0-031b865f3cc7’, sessionKey: ‘b5d92c9f-6bb1-4344-a00a-515bb2b99513’, baseUri: 'http://igloodeveloperrelations.igloodigitalworkplace.ca/.api/api.svc/', baseUriHttps: 'https://igloodeveloperrelations.igloodigitalworkplace.ca/.api/api.svc/', customSessionKey: '', authInstance: null, tenantId: 'CAMLT' }
We retrieved the session key, which was our goal! The userId represents the user who authenticated to Igloo, and the sessionKey will be used to create subsequent calls.
Now that we have the session key — what is the next step?
In the code example above, we stored our session token in the cookie variable.
var cookie = "iglooauth=" + response.data.response.sessionKey
Using cookie, we can start to make subsequent calls. Let’s look at a couple of APIs to get you started and comfortable with the process.
This first API call is straightforward because there are no parameters. We can call this endpoint and see the response in the terminal.
We will be using the endpoint for account profile view:
/.api/api.svc/account/profile/view
var callUrl = community + "/.api/api.svc/account/profile/view" axios.get(callUrl, { headers: { Cookie: cookie } }) .then(function(response) { console.log(response.data.response); }).catch(function(error) { console.log(error); })
In the above code snippet, we create a new variable called callURL to store the path to the API call — we only need the community and API path/endpoint since there are no parameters.
We create a GET method (axios.get) to retrieve and view our account information without changing it.
The response:
{
__type: 'User:http://schemas.iglooplatform.com/Igloo.Old.Common',
id: '623af5d7-06e4-4bfe-984e-95c45009b3a0',
href: '',
navType: 0,
persona: {
id: ' b139150c-e8c5-4869-a506-1c70456f3e46',
href: '/.profile/ksander2',
navType: 0,
isEnabled: true,
name: {
firstName: 'Kristin',
lastName: 'Sander',
fullName: 'Kristin Sander',
initials: 'KS'
},
namespace: 'ksander2',
isActivated: true,
onlinestatus: { lastvisit: '2021-10-29T10:22:37-05:00', statusText: '' },
status: {},
anonymousname: '',
hasPhoto: false,
sharePhoto: true,
email: 'ksander@igloosoftware.com',
sendEmailOnMessage: true,
smsAddress: '',
address: {},
bio: '',
company: '',
phone: '',
website: ''
}
In the response, you can see all your account information, such as email, username, the time you last visited the digital workplace, etc. Because we’re printing it out, it can all be seen in the terminal.
Let’s look at another slightly more complicated example.
In this second API call, we will view all the members of the digital workplace.
We will be using the following endpoint to view all the members:
/.api/api.svc/account/profile/view
We will need two parameters, maxcount which is the number of elements to retrieve, and startindex, which determines what index position to start retrieving the elements from. We can store these parameters in separate variables so that we can update them later if we need to.
We can put 10 for maxcount because that’s the default value and 0 for startindex to tell the server to start at the top of the list. You can change this according to the information you require.
Pagination is a method that divides up content into several other pages, presenting a subset of the data. You can make subsequent API calls to retrieve additional users by changing the startindex. For more information on pagination and design, see What is Pagination (WhatIs.com).
var maxcount= 10; var startindex= 0; var callUrl = community + "/.api/api.svc/apisync/view_members?maxcount=" + maxcount + "&startindex=" + startindex; axios.get(callUrl, { headers: { Cookie: cookie } }) .then(function(response) { console.log(response.data.response); }).catch(function(error) { console.log(error); })
Response:
{ __type: 'Model.SyncUser:http://schemas.iglooplatform.com', id: ' 258959c0-a8b3-44ba-9829-3766697fcd54', href: '', navType: 0, Email: 'ksanders@igloosoftware.com', IsAdmin: true, IsDelegated: false, Name: [Object], PreferredLanguage: 1 }, { __type: 'Model.SyncUser:http://schemas.iglooplatform.com/Igloo', id: '99af1a1b-dca5-446b-8d77-7e19971c8ecd', href: '', navType: 0, Email: 'thuber@igloosoftware.com', IsAdmin: true, IsDelegated: false, Name: [Object], PreferredLanguage: 1 }, { __type: 'Model.SyncUser:http://schemas.iglooplatform.com', id: '031b63ff-2308-48e4-8fef-1924ecce710b', href: '', navType: 0, Email: 'privera@igloosoftware.com', IsAdmin: true, IsDelegated: false, Name: [Object], PreferredLanguage: 1 }
In the response, you can see the first 10 members that are in your digital workplace and details about them such as their email, if they are an admin, etc.
Congratulations, you have authenticated into Igloo and have made your first two API calls! Igloo has many APIs that can be used to GET and POST content, users, and groups to your digital workplace.
For more information, please visit Igloo’s developer portal.