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

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}.hotdocsadvance.com/auth/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.

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

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://tenancy1.hotdocsadvance.com/auth/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

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.

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 Auth application
            var clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";
            // The endpoint for retrieving the access token
            var requestUrl = "https://yourtenancy.hotdocsadvance.com/Auth/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 HandleToken endpoint accepts GET requests
  • The HandleToken endpoint returns a view; the URL of this view contains the access token as a URL fragment, denoted by a hash (#) character
  • The token is retrieved from the page URL by JavaScript

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 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();
        }
    }
}

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>