Getting an Access Token Using the Resource Owner 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 ResourceOwner flow.

In this Topic Hide

  1. Prerequisites
  2. Overview
  3. Request
  4. Authentication
  5. Code Example

Prerequisites

Overview

This request retrieves an access token from Advance, using a service principal account. Once you successfully retrieve the access token, you can then use it to sign requests to the Advance API.  

Request

Request URL

POST https://{tenancymoniker}.{domain}/HdaAuth/Authorize/ServicePrincipalLogIn

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 Request body Yes The unique name of the client making the request; you can see the client's unique name on the client details page.
PrincipalName String Request body
 		 Yes

The name of the service principal user associated with the client specified above.

PrincipalPassword

 String Request body
 		 Yes

The password of the service principal user specified above. This password was set when the service principal was created.

Examples

Example Request URL

https://yourtenancy.yourorganization.com/HdaAuth/Authorize/ServicePrincipalLogIn

Example Request Body (JSON)

{

    "ClientName": "yourTenancy17ABSHVJL",

    "PrincipalName": "ExamplePrincipal01",

    "PrincipalPassword": "examplepassword",

}

Example Response

Status: 200 OK

Content-type: text/plain

Body: [token string]

Authentication

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

Code Example

See Resource Owner Flow Authorization Example for further examples.

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace HotDocsAdvanceApiExamples
{
    public class ResourceOwnerAuthorization
    {
        // These are the credentials required for retrieving an access token using the resource owner flow.
        // You will replace these credentials with those for a client you create yourself,
        // using the Advance Client Management Application. See the API help guide for more information.
        private string clientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6";
        private string servicePrincipalName = "ExampleServicePrincipalA";
        private string servicePrincipalPassword = "examplePassword";

        public async Task<string> GetResourceOwnerToken()
        {
            // Create the access token request            
            var request = CreateHttpRequestMessage();

            //Send token request to Advance
            using (var client = new HttpClient())
            {
                var response = await client.SendAsync(request);

                // Return the retrieved access token
                return response.Content.ReadAsStringAsync().Result;
            }
        }

        private HttpRequestMessage CreateHttpRequestMessage()
        {
            var tokenUrl = string.Format("https://yourtenancy.yourorganization.com/HdaAuth/Authorize/ServicePrincipalLogIn");

            return new HttpRequestMessage
            {
                RequestUri = new Uri(tokenUrl),
                Method = HttpMethod.Post,
                Content = GetRequestContent()
            };
        }

        private StringContent GetRequestContent()
        {
            var json = "{" + string.Format("'ClientName' : '{0}', 'PrincipalName' : '{1}', 'PrincipalPassword' : '{2}'", clientName, servicePrincipalName, servicePrincipalPassword) + "}";
            return new StringContent(json, Encoding.UTF8, "application/json");
        }
    }
}