CIX Developer Documentation

Authentication Guide

Authentication of requests to the CIX API is via OAuth2. The CIX API offers two approaches for authentication. Desktop Client is intended for native clients where no web browser is present to allow the user to authenticate via the CIX Login page. Web Client is more secure and is intended primarily for web applications but can also be used by native applications if a web API is available.

Unlike earlier versions of the API, Basic Authentication is no longer supported. However if your client currently uses Basic Authentication then it is quite easy to adapt it to use Desktop Client authentication requests.

Desktop Client Authentication

This method of authentication allows a client to send a username and password to the API authentication service and receive an access token back. This access token then allows the authenticated user access to the API services. Because the user enters their login credentials on the client, this is considered less secure than Web Client authentication and the onus is on the developer to ensure that credentials are secured and passed through securely.

To use this method, you will first need to create a Desktop client from the Clients page. Specify an unique client Id and give it a descriptive name (which can be anything you wish as it is not used as part of the authentication). You will also need to specify a secret string which is simply a sequence of characters and digits.

The following C# code shows an example of how to obtain details of the cixnews forum via this method. (The client Id and secret used here are generic for testing.)

        public static async Task<string> GetResponse() {

            HttpClient _client = new HttpClient(new HttpClientHandler());

            // Call the OpenID configuration source
            HttpResponseMessage response = await _client.GetAsync("https://api.cix.uk/.well-known/openid-configuration", 
                default(CancellationToken)).ConfigureAwait(false);
            if (!response.IsSuccessStatusCode) {
                return response.ReasonPhrase;
            }

            // Read the discovery data
            string disco = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
            string tokenEndPoint = JObject.Parse(disco)["token_endpoint"].ToString();

            string username = "your_cix_username";
            string password = "your_cix_password";

            string yourClientId = "cixDesktop";
            string yourClientSecret = "secret";

            // To get the access token, we need to pass through the CIX username and password as the
            // form data, specifying grant type as 'password' for Resource Owner Password Grant. The
            // scope is also required to specify the part of the API to which we're requesting access.
            var fields = new Dictionary<string>, string> {
                { "grant_type", "password" },
                { "username", username },
                { "password", password },
                { "scope", "cixApi3" }
            };

            // Pass through the client Id and secret as the authentication scheme.
            Encoding encoding = Encoding.UTF8;
            string credential = String.Format("{0}:{1}", yourClientId, yourClientSecret);

            var request = new HttpRequestMessage(HttpMethod.Post, tokenEndPoint) {
                Content = new FormUrlEncodedContent(fields),
            };

            request.Headers.Authorization = new AuthenticationHeaderValue("basic", Convert.ToBase64String(encoding.GetBytes(credential)));

            // Now get the access token required for making the API call
            string accessToken;
            try {
                response = await _client.SendAsync(request, default(CancellationToken)).ConfigureAwait(false);
                if (!response.IsSuccessStatusCode) {
                    return response.ReasonPhrase;
                }
                if (response.Content == null) {
                    return "Empty content";
                }
                string content = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
                accessToken = JObject.Parse(content)["access_token"].ToString();
            }
            catch (Exception ex) {
                return ex.Message;
            }

            // Now that we have an access token, we can use it to make the API call by specifying the
            // access token in the Bearer header field.
            var client = new HttpClient();
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            // Call the API
            response =  await client.GetAsync("https://api.cix.uk/v3.0/Forum/cixnews/details");
            if (!response.IsSuccessStatusCode) {
                return response.StatusCode.ToString();
            }

            // Return the response
            return await response.Content.ReadAsStringAsync();
        }
    

You can download the full source code here (requires .NET Framework 4.6 and Newtonsoft.Json).

Web Client Authentication

This method of authentication requires the client to open a browser session to the API authentication endpoint which will display a login screen followed by a consent screen. The end user must login and consent to the appropriate grants before an access token is returned back to the client. The client can then use that access token to invoke methods on the API under the credentials of the authenticated user.

To use this method, you will first need to create a Web client from the Clients page. Specify an unique client Id and give it a descriptive name (which can be anything you wish as it is not used as part of the authentication). You will also need to specify the base URL of your website which, during debugging, will be localhost.

The following C# code shows an example of how to obtain details of the cixnews forum via this method. Prior to calling this code you should have called UseOpenIdConnectAuthentication in the startup and registered a web client of your own. The URL of the client will typically be the localhost URL of the debugging session.

        [Authorize]
        public async Task<IActionResult> Index() {

            string accessToken = await HttpContext.Authentication.GetTokenAsync("access_token");

            using (HttpClient client = new HttpClient()) {

                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

                HttpResponseMessage response = await client.GetAsync("https://api.cix.uk/v3.0/Forum/cixnews/details");

                if (response.StatusCode == HttpStatusCode.Unauthorized) {
                    return NoContent();
                }

                string content = await response.Content.ReadAsStringAsync();

                if (!string.IsNullOrEmpty(content)) {
                    ViewBag.Details = content;
                }
            }

            return View();
        }
    

You can download the full source code here (requires .NET Core 1.1).