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.

Prerequisites

Create a new API client – you must have an existing API client that uses the ResourceOwner flow
Adding a service principal to a client – the API client above must have an associated service principal user

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