Who Are You? – Authenticating To Igloo

Making any API call against IGLOO requires you to authenticate. Authentication creates a session key which holds the context of the user who authenticated. If you create a blog while authenticated as Joe, the creation event will be attributed to Joe.

Authentication requires that you have:

• an appId and an appPassword 
• a digital workplace and user credentials

These are provided to you when you register as a developer. 

Authenticating using v1 and v2 Examples

There are three ways to use our session/create endpoints. In these examples I will show you how to create a session using the latest version of NodeJS, the native querystring package, and axios for API calls.

Axios (https://github.com/axios/axios) is a JavaScript library that’s great for making HTTP requests from within NodeJS. 

Querystring is a NodeJS module for parsing URL strings. Check out NodeJS documentation for more information

Authenticating using APIv1 using NodeJS

Let’s take a look at authenticating with the v1 /.api/api.svc/session/create  endpoint.

Here’s an example:

Fg:1 Making an API call with the v1 session/create endpoint

We imported querystring and axios and the structure of our object is as follows:

const params = {
"appId": "YOUR_APP_ID",
"appPass": "YOUR_APP_PASSWORD",
"username": "YOUR_IGLOO_USERNAME",
"password": "YOUR_IGLOO_PASSWORD",
"community": "COMMUNITY_DOMAIN (domain.com --make sure to leave out the https )",
  "apiversion": 1 /* This is a constant it will always be 1 */
 };

With our object populated, we will create a function that will make the API call. Since axios is promise based we don’t need to worry about creating promises. For more information about axios, visit their GitHub repository link.

This is what the complete v1 snippet looks like:

Our function returns (in the console log) the response using our API KEY and password. The userId indicates the user who created the session and the sessionKey is the key we need to create calls against the digital workplace moving forward.

Authenticating using APIv2

There isn’t much of a difference between v1 and v2 in terms of the parameter object, however, the return schemas differ. Additionally, the v2 endpoint cannot be used with digital workplaces that use SAML authentication. We will touch upon these topics in a future article.

const params = {
"AppId": "YOUR_APP_ID",
"AppPassword": "YOUR_APP_PASS",
"UserName": "YOUR_IGLOO_USERNAME",
"UserPassword": "YOUR_IGLOO_PASSWORD",
  "instance": 0/* based on your sign in configuration. If you haven't made any changes to it than this should be 0 */
 };

As you can see, the structure is a little different. Using the v2 endpoint, the platform can already detect what digital workplace we’re using so there is no need to pass that as a parameter. 

The Instance parameter is interesting - depending on your site configuration you can set the instance to use whichever config you think is appropriate. 

 An important note, v2 consumes the parameters in the body of the post rather than as query parameters - passing them as query parameters will throw an error.

This is how the complete v2 snippet looks like:

{ 

  TokenId: 'ee0cd350-466b-4bca-972f-f08063570f31', 

  UserId: '8ed95674-6a0c-4018-b612-b316ffa055c9',

  Expiry: '2019-03-11T20:49:45.573', 

  RememberExpiry: null,

  AppId: 'a83df4cb-8811-43cd-a0db-284c80344661', 

  SecretKey: 'f7ef440c-e4f6-439c-9499-7515f65e8a6b',

  PrivatePlatformKey: 'c3d63e0a-94cd-47fd-91c2-9bf39fc7d788', 

  BaseUri: 'bobbycorp.igloocommunities.com/.api/api.svc/',

  CustomSessionToken: '', 

  CommunityID: 'd77421d3-41f5-4f63-8494-5e95317cc0c5',

  IsValid: true  

}

Versioned v2 endpoint

If you have LDAP auth configured and you want to use that configuration in your authentication step you can do that by passing the v1 path parameter. The AppID and AppPassword stay the same however now you want to pass the instance number associated with your LDAP sign in configuration and your LDAP credentials for username and password. The return schema is the same as the non-versioned v2 endpoint and the parameter object is also similar in structure.

Different methods of authentication (v1 and v2 and differences)

There are a few noticeable differences in how these endpoints return a sessionKey.

 The v2 endpoint does not work with SAML enabled digital workplaces since SAML itself is its own method of authentication, the v1 endpoint was written before SAML was introduced which is why you’re able to create a session using it but v2 is more focused on LDAP Auth.

Another key difference between the two endpoints is the return data structure. The v1 endpoint uses a more complex response schema which means you need to drill down to the response object that holds are the keys regarding session. In contrast, the v2 endpoint returns a TokenId (same as sessionKey) and doesn’t require you to dig a layer deeper, it’s available at the root level.

Wrapping Up

Either v1 or v2 methods will work for you as long as you have an API key and password. You don’t need to worry about using a different key or password for each version of session/create – they all work.