Reference Topic

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.

Prerequisites

• Create a new API client – you must have an existing API client that uses the Implicit flow

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:

• You redirect your user to Advance's sign-in page (the "request URL"), specifying:
  • The URL in your application to which Advance returns (the "return URL") once the sign-in is complete; and
  • How you want Advance to return the access token (the "response mode")
• The user logs into Advance using their credentials
• The Advance sign-in page redirects back to your Application, using the return URL you specify
• You retrieve the access token; how you retrieve the access token depends on the response mode. See the Response Modes section for more information.

Request

Request URL

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

Parameters

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 – Advance posts the access token to the specified return URL
• Fragment – Advance returns the access token as a URL fragment, denoted by a hash (#) character
• Cookie – Advance returns the access token in a browser cookie

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
• Using the Fragment response mode
• Using the Cookie response mode

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 Auth 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

using Microsoft.AspNetCore.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
            const string clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";
            // The endpoint for retrieving the access token
            const string requestUrl = "https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn";
           
            // The endpoint (HandleToken, below) in your application to which the token is returned            
            const string returnUrl = "https://yourorganization.com/YourApplication/Auth/HandleToken";
           
            // The type of response, containing the access token, returned from Advance            
            const string responseMode = "Fragment";
           
            // The completed request URL, using the values specified above. You then redirect to the Advance login page            
            return Redirect($"{requestUrl}?clientName={clientName}&returnUrl={returnUrl}&responseMode={responseMode}");      
        }    
       
        [HttpGet]        
        public ActionResult HandleToken()  
        {                
            return View();
        }
    }
}

<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 Microsoft.AspNetCore.Mvc;
namespace HotDocsAdvanceApiExamples.Controllers;
public class AuthController : Controller
{
    public ActionResult Implicit()
    {
        // The name of client making the request, created through the Advance Auth application
        const string clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";
        // The endpoint for retrieving the access token
        const string requestUrl = "https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn";
        // The endpoint (HandleToken, below) in your application to which the token is returned
        const string returnUrl = "https://yourorganization.com/YourApplication/Auth/HandleToken";
        // The type of response, containing the access token, returned from Advance
        const string responseMode = "Cookie";
        // The completed request URL, using the values specified above. You then redirect to the Advance login page
        return Redirect($"{requestUrl}?clientName={clientName}&returnUrl={returnUrl}&responseMode={responseMode}");
    }
    [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
        var token = HttpContext.Request.Cookies["apiToken"];
        // Todo: Use the token to make requests to the Advance API
    }
}

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");