Security and Authentication

In order to use the Interact API you must be a verified user. The API will obey any permissions that have been assigned to the user through the website, meaning that users will only be able to access content through the API that they would be able to access.

Direct authentication is only required through the token system if using the API outside of your interact instance. Interact offers the ability to enter custom javascript in free text widgets or in the MasterPage javascript functionality. If using the API from a widget or the developer framework then authentication is taken from the user that is logged into your interact intranet and therefore explicit authentication is not required.

If accessing the API via an environment that is outside of your Interact instance, then authentication is required. To authenticate against the API, use the /token endpoint and pass the user's username and password (note: this endpoint does not include the /api/ part of the path). If the user is successfully authenticated, then this endpoint will return an access token in its response. This access token then needs to be submitted in the authorization header for every request.

The example C# code shown below authenticates a user, then requests a list of people, before writing each person's Id and Name to the console.

static void Main(string[] args)
{
	var tenant = new Guid("e822a190-a116-4779-ad0a-87631b51898a");
	var apiDomain = "{{your_ApiDomain}}";

	var username = "w.skroob";
	var password = "12345";
	
	var accessToken = "";
			
	// do login
	var body = new Dictionary<string, string>();

	body.Add("grant_type", "password");
	body.Add("username", username);
	body.Add("password", password);

	var resp = Post($"{apiDomain}/token", body, tenant);

	dynamic obj = JsonConvert.DeserializeObject(resp);

	accessToken = obj.access_token;
	refreshToken = obj.refresh_token;

	dynamic people = JsonConvert.DeserializeObject(Get($"{apiDomain}/api/people", tenant, accessToken));

	foreach (dynamic person in people.Results)
	{
		Console.WriteLine($"{person.personId} - {person.FullName}");
	}
}

static string Post(string url, Dictionary<string, string> form, Guid tenant)
{
	HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
	request.Headers.Add("X-Tenant", tenant.ToString());
	request.Method = "POST";

	string body = QueryString(form);

	System.Text.UTF8Encoding encoding = new System.Text.UTF8Encoding();
	Byte[] byteArray = encoding.GetBytes(body);

	request.ContentLength = byteArray.Length;
	request.ContentType = @"application/x-www-form-urlencoded";

	using (Stream dataStream = request.GetRequestStream())
	{
		dataStream.Write(byteArray, 0, byteArray.Length);
	}

	try
	{
		WebResponse response = request.GetResponse();
		using (Stream responseStream = response.GetResponseStream())
		{
			StreamReader reader = new StreamReader(responseStream, Encoding.UTF8);
			return reader.ReadToEnd();
		}
	}
	catch (WebException ex)
	{
		WebResponse errorResponse = ex.Response;
		using (Stream responseStream = errorResponse.GetResponseStream())
		{
			StreamReader reader = new StreamReader(responseStream, Encoding.GetEncoding("utf-8"));
			string errorText = reader.ReadToEnd();
		}
		throw;
	}
}

static string Get(string url, Guid tenant, string accessToken)
{
	HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
	request.Headers.Add("X-Tenant", tenant.ToString());
	request.Headers.Add("Authorization", $"Bearer {accessToken}");

	try
	{
		WebResponse response = request.GetResponse();
		using (Stream responseStream = response.GetResponseStream())
		{
			StreamReader reader = new StreamReader(responseStream, Encoding.UTF8);
			return reader.ReadToEnd();
		}
	}
	catch (WebException ex)
	{
		WebResponse errorResponse = ex.Response;
		using (Stream responseStream = errorResponse.GetResponseStream())
		{
			StreamReader reader = new StreamReader(responseStream, Encoding.GetEncoding("utf-8"));
			string errorText = reader.ReadToEnd();
		}
		throw;
	}
}

static byte[] GetBytes(string url, Guid tenant, string accessToken)
{
	HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
	request.Headers.Add("X-Tenant", tenant.ToString());
	request.Headers.Add("Authorization", $"Bearer {accessToken}");

	try
	{
		WebResponse response = request.GetResponse();
		using (Stream responseStream = response.GetResponseStream())
		{
			using (MemoryStream ms = new MemoryStream())
			{
				responseStream.CopyTo(ms);
				return ms.ToArray();
			}
		}
	}
	catch (WebException ex)
	{
		WebResponse errorResponse = ex.Response;
		using (Stream responseStream = errorResponse.GetResponseStream())
		{
			StreamReader reader = new StreamReader(responseStream, Encoding.GetEncoding("utf-8"));
			string errorText = reader.ReadToEnd();
		}
		throw;
	}
}

public static string QueryString(IDictionary<string, string> dict)
{
	var list = new List<string>();
	foreach (var item in dict)
	{
		list.Add(item.Key + "=" + item.Value);
	}
	return string.Join("&", list);
}