Getting an Access Token using the Implicit Flow

You must sign your requests with an access token when making requests to the HotDocs Advance API. This topic describes how to retrieve an access token using the Implicit flow.

In this Topic Hide

  1. Prerequisites
  2. Overview
  3. Request
  4. Response Modes
    1. FormPost
    2. Fragment
    3. Cookie
  5. Authentication
  6. Code Example (C#)
    1. Using the FormPost response mode
    2. Using the Fragment response mode
    3. Using the Cookie response mode

Prerequisites

Overview

This request enables you to retrieve an access token from Advance. The client gets a token as part of a sign-in process for a real user, without needing a secret. You will typically want to use this authorization flow when the application you need to integrate with Advance is a single-page application.

In your application, retrieving the access token requires the following steps:

Request

Request URL

GET https://{tenancymoniker}.{domain}/HdaAuth/Authorize/LogIn?clientName={clientName}&returnUrl={returnUrl}&responseMode={responseMode}

Parameters

Name Type Location Required Description
tenancymoniker String URL Yes The tenancy moniker for the tenancy in which you want to initialize a work item.
domain String

URL

 Yes Your domain. For example, yourorganization.com.

clientName

 String Query string Yes The unique name of the client making the request; you can see the client's unique name on the client details page.

returnUrl

 String Query string Yes The URL of the endpoint in your application to which the token is returned.

responseMode

 String Query string Yes The access token can be returned in the following response modes:
  • FormPost
  • Fragment
  • Cookie

See the Response Modes section for more information.

ignoreSso

 Boolean Query string No Defaults to false. If set to true, the configured single-sign on provider is ignored and Advance uses the default authentication method.

Examples

Example Request URL

https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn?clientName=ab3e4544-b595-4681-b0ea-c7c18c9b63f6&returnUrl=https://yourorganization.com/YourApplication/HandleToken&responseMode=fragment

Response Modes

The implicit flow can return an access token to your application using these response modes:

FormPost

When using the FormPost response mode, Advance posts the access token to the endpoint specified in the returnUrl parameter. The endpoint must accept the POST HTTP verb. You retrieve the access token from the response's form, using the ApiToken key. For example, in ASP.Net you can use Request.Form["ApiToken"];.

See Using the FormPost response mode for a code example.

Fragment

When using the fragment response mode, Advance appends the access token to the return URL as a fragment, denoted by the hash (#) character. For example:

http://yourorganization.com/yourapplication/Home/ReceiveToken#{accesstoken}

Where everything before the # character is your return URL and {accesstoken} is a placeholder for the access token.

Once the Advance sign-in is complete, you are redirected back to the return URL. The application endpoint specified in the return URL must load an HTML page. On this HTML page, you can use JavaScript to read the token from the page URL. For example, by using window.location.hash.

See Using the Fragment response mode for a code example.

Cookie

When using the cookie response mode, Advance stores the access token in a browser cookie named apiToken. The cookie is available once the redirection back to your application from the Advance sign-in is completed. You retrieve the access token by reading the value of the cookie. For example, in ASP.Net, you can read the token using HttpContext.Request.Cookies["apiToken"].Value;.

See Using the Cookie response mode for a code example.

Authentication

See Authentication for more information about using the returned token when authenticating requests to the Advance API.

Code Example (C#)

The code examples explain how to retrieve the access token using the following response modes:

Using the FormPost response mode

In this example, Advance returns the access token to the endpoint you specify as the returnUrl. The return URL must accept HTTP POST requests.

Controller

The AuthController controller file. The returnUrl value must match the return URL for the specified client (the client's return URL is set when creating your API client).

using System.Web.Mvc;


namespace HotDocsAdvanceApiExamples.Controllers
{
    public class AuthController : Controller
    {
        public ActionResult Implicit()
        {
            // The name of client making the request, created through the Advance Client Management application
            var clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";

            // The endpoint for retrieving the access token
            var requestUrl = "https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn";
            // The endpoint (HandleToken, below) in your application to which the token is returned
            var returnUrl = "https://yourorganization.com/YourApplication/Auth/HandleToken";

            // The type of response, containing the access token, returned from Advance
            var responseMode = "FormPost";

            // The completed request URL, using the values specified above. You then redirect to the Advance login page
            var url = string.Format("{0}?clientName={1}&returnUrl={2}&responseMode={3}", requestUrl, clientName, returnUrl, responseMode);
            return Redirect(url);
        }

        [HttpPost]
        public ActionResult HandleToken()
        {            

            // Retrieve the access token; you can then use the token to make requests to the Advance API
            var token = Request.Form["ApiToken"];
        }
    }
}

Using the Fragment response mode

This example differs from the FormPost example in the following ways:

The example below is for a ASP.NET web application project, connecting to an on-premise instance of HotDocs Advance.

Controller

The AuthController controller file. The returnUrl value must match the return URL for the specified client (the client's return URL is set when creating your API client).

using System.Web.Mvc;


namespace HotDocsAdvanceApiExamples.Controllers
{
    public class AuthController : Controller
    {
        public ActionResult Implicit()
        {
            // The name of client making the request, created through the Advance Client Management application
            var clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";

            // The endpoint for retrieving the access token
            var requestUrl = "https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn";

            // The endpoint (HandleToken, below) in your application to which the token is returned
            var returnUrl = "https://yourorganization.com/YourApplication/Auth/HandleToken";

            // The type of response, containing the access token, returned from Advance
            var responseMode = "Fragment";

            // The completed request URL, using the values specified above. You then redirect to the Advance login page
            var url = string.Format("{0}?clientName={1}&returnUrl={2}&responseMode={3}", requestUrl, clientName, returnUrl, responseMode);
            return Redirect(url);
        }

        [HttpGet]
        public ActionResult HandleToken()
        {            
            return View();
        }
    }
}

View

The HandleToken view. In this example, the token is retrieved from the URL and placed in a text area for you to view. From this page, the token can then be used when making requests to the Advance API.

<textarea id="token"></textarea>


<script type="text/javascript">
     // Display the token in the textarea.
     document.getElementById("token").value = window.location.hash;
</script>

 

Using the Cookie response mode

In this example, Advance returns you to the endpoint you specify as the returnUrl. The return URL must accept HTTP GET requests. When you return to your application, and the request has completed, you can read the cookie set by Advance.

Controller

The AuthController controller file. The returnUrl value must match the return URL for the specified client (the client's return URL is set when creating your API client).

using System.Web.Mvc;


namespace HotDocsAdvanceApiExamples.Controllers
{
    public class AuthController : Controller
    {
        public ActionResult Implicit()
        {
            // The name of client making the request, created through the Advance Client Management application
            var clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";

            // The endpoint for retrieving the access token
            var requestUrl = "https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn";
            // The endpoint (HandleToken, below) in your application to which the token is returned
            var returnUrl = "https://yourorganization.com/YourApplication/Auth/HandleToken";

            // The type of response, containing the access token, returned from Advance
            var responseMode = "Cookie";

            // The completed request URL, using the values specified above. You then redirect to the Advance login page
            var url = string.Format("{0}?clientName={1}&returnUrl={2}&responseMode={3}", requestUrl, clientName, returnUrl, responseMode);
            return Redirect(url);
        }

        [HttpGet]
        public ActionResult HandleToken()
        {            
            // Return the user to the application; to read the access token from the cookie, call the GetToken endpoint, below
            return View();
        }
 
        [HttpGet]         

        public void GetToken()         

        {            

            // Read the access token from the cookie; you can then use the token to make requests to the Advance API 

            var token = HttpContext.Request.Cookies["apiToken"].Value;

        }
    }
}

View

The HandleToken view. The view contains a link to the GetToken endpoint, to demonstrate the retrieval of the access token from the cookie.

@Html.ActionLink("Get token", "GetToken", "Home");