Api Documentation

This page offers comprehensive information about the api's available with CitC. There are api's available for the following as of now:

• Users
• Organizations
• Parameters

Lets look at each one of them. As and when more api methods are added, this page will be updated.

Quickstart

In order to call any of the api's listed here, you should use the following method. Example given below describes how the organization api can be used to get the details of a certain organization identified by the guid available in the claims.

        [Authorize]
        public async Task<IActionResult> CallOrganizationsApiUsingUserAccessToken()
        {
            var accessToken = await HttpContext.Authentication.GetTokenAsync("access_token");

            var claimsIdentity = HttpContext.User.Identity as ClaimsIdentity;
            var orgClaim = claimsIdentity.FindFirst("Organization");

            var client = new HttpClient();
            client.SetBearerToken(accessToken);
            var content = await client.GetStringAsync($"https://citc-server-prod.azurewebsites.net/api/Organizations/{orgClaim.Value}");

            ViewBag.Json = GetFormattedJson(content);
            return View("json");
        }
        

You also have to add the following nuget package in order to call the API

• IdentityServer4.AccessTokenValidation

Refresh Tokens

The api tokens you get from the identity server have a life time and may expire. So while using the API you will have to watch for errors and request a refresh token. This can be done as shown below:

        public async Task<IActionResult> Index()
        {
            var disco = await DiscoveryClient.GetAsync(_idServerSettings.Url);
            if (disco.IsError) throw new Exception(disco.Error);

            var tokenClient = new TokenClient(disco.TokenEndpoint, "<app_id>", "<app_secret>");
            var rt = await HttpContext.Authentication.GetTokenAsync("refresh_token");
            var tokenResult = await tokenClient.RequestRefreshTokenAsync(rt);

            if (!tokenResult.IsError)
            {
                var old_id_token = await HttpContext.Authentication.GetTokenAsync("id_token");
                var new_access_token = tokenResult.AccessToken;
                var new_refresh_token = tokenResult.RefreshToken;

                var tokens = new List();
                tokens.Add(new AuthenticationToken { Name = OpenIdConnectParameterNames.IdToken, Value = old_id_token });
                tokens.Add(new AuthenticationToken { Name = OpenIdConnectParameterNames.AccessToken, Value = new_access_token });
                tokens.Add(new AuthenticationToken { Name = OpenIdConnectParameterNames.RefreshToken, Value = new_refresh_token });

                var expiresAt = DateTime.UtcNow + TimeSpan.FromSeconds(tokenResult.ExpiresIn);
                tokens.Add(new AuthenticationToken { Name = "expires_at", Value = expiresAt.ToString("o", CultureInfo.InvariantCulture) });

                var info = await HttpContext.Authentication.GetAuthenticateInfoAsync("Cookies");
                info.Properties.StoreTokens(tokens);
                await HttpContext.Authentication.SignInAsync("Cookies", info.Principal, info.Properties);

                return Redirect("~/Home/Secure");
            }

            ViewData["Error"] = tokenResult.Error;
            return View("Error");
        }
    

            app.UseOpenIdConnectAuthentication(new OpenIdConnectOptions
            {
                AuthenticationScheme = "oidc",
                SignInScheme = "Cookies",

                // ...                

                Scope = { "role", "Organization", "concertCloudApi", "offline_access" },

                // ...
            });
    

Users Api

    Method:        Get
    Parameter(s):  -
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Users
    Returns:       Json representing various details about the current logged in user, including the roles (global, application, organization)

    Method:        GetById
    Parameter(s):  userId
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Users/GetById/{UserId}
    Returns:       Json representing various details about the user, including the roles (global, application, organization)

    Method:        GetAll
    Parameter(s):  -
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Users/GetAll
    Returns:       Json representing all the users (only the user id, display name)

Organizations Api

    Method:        Get
    Parameter(s):  organizationId
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Organizations/{OrganizationId}
    Returns:       Json representing various details about the organization with the id specified in the request

    Method:        GetByUser
    Parameter(s):  -
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Organizations/GetByUser
    Returns:       Json representing various details about the organziations that the logged in user can access

    Method:        GetAll
    Parameter(s):  -
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Organizations/GetAll
    Returns:       Json representing all the organizations known to CitC

Parameters Api

    Method:        Get
    Parameter(s):  -
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Parameters
    Returns:       Json representing all the global parameters

    Method:        GetByApplication
    Parameter(s):  applicationId (used during app registration in CitC)
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Parameters/GetByApplication/{ApplicationId}
    Returns:       Json representing all the parameters that is specific to this application

    Method:        GetByOrganization
    Parameter(s):  organizationId
    Api Url:       https://citc-server-prod.azurewebsites.net/api/Parameters/GetByOrganization/{OrganizationId}
    Returns:       Json representing all the parameters that is specific to this organization