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

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
        {
        public static async Task<string> GetResourceOwnerTokenAsync()
        {
            using var client = new HttpClient();
            var request = new HttpRequestMessage
            {
                RequestUri = new Uri("https://yourtenancy.yourorganization.com/HdaAuth/Authorize/ServicePrincipalLogIn"),
                Method = HttpMethod.Post,
                Content = JsonContent.Create(new
                {
                    ClientName = "ab3e4544-b595-4681-b0ea-c7c18c9b63f6",
                    PrincipalName = "ExampleServicePrincipalA",
                    PrincipalPassword = "examplePassword"
                })
            };
            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadAsStringAsync();
        }
    }
}