Set Up Guide

1. Open a web browser.
2. Navigate to the application using the following URL:
   https://{tenancymoniker}.yourorganization.com/HdaAuth
   Where tenancymoniker is replaced with the tenancy you want to access and yourorganization.com is replaced with your own domain.
3. Type your username and password into the fields.
4. Click the Login button; you are taken to the API Client Management landing page.

1. Log into the API Clients Management application.
2. Click the Manage Client Credentials link.
3. Click the Create a new client link.
4. In the Create a new client form, enter the following information:
   1. DisplayName – a 'friendly' descriptive name for the client, used to identify the client in the UI
   2. FlowType – the type of authorization flow used by the client; select a flow type from the following options:
      • ResourceOwner – the client gets tokens by impersonating a service account
      • Implicit – the client gets a token as part of a sign-in process for a real user, without needing a secret
   3. Secret – the secret for the client, used for authentication
   4. ReturnUrl – the URL to which responses from the API are returned; not used by clients that use the Resource Owner flow
   5. LandingPage – the URL for the landing page to which new users are redirected from the provisioning e-mail; only used by users created via the API
   6. Token life span – the number of seconds for which the token is valid
   7. Scope – select from the following options:
      • Query – the client can only make read requests to the API
      • Command – the client can make read and write requests to the API
      • Root – the client has full root access to Advance; it can issue user access tokens
5. Click the Create button; the Client Details page appears.
6. (Optional) Click Activate Client; if you do not want to make the client immediately available, you can activate it later.

1. Open the details page for the client for which you need to add a service principal
2. Click the Add a service principal button.
3. Enter the following information into the Add a service principal for the client form:
• PrincipalName – the name of the new service principal
• (Optional) Password – an automatically-generated password appears in this field; you can change it to your own custom password, if necessary.

  Note: You must remember this password; it cannot be viewed again beyond this page. You will require the password when making requests to the Advance API.

• (Optional) IsActive – check this box to make the service principal available for making requests to the API; you can activate the service principal later, if necessary.

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

The URL consists of the path to the Advance API application and the API version you want to use. The format of the URL is typically:

• https://{tenancyMoniker}.{serverName}.{yourDomain}/HdaApi/rest/v{apiVersionNumber}/

Where:

• tenancyMoniker – the name of the Advance tenancy against which you are making requests; for example, tenancy1
• serverName – the server on which Advance is installed; for example, testserver01
• yourDomain – the domain under which Advance is installed; for example, yourorganization.com
• apiVersionNumber – the version number of the Advance API you are using; the latest version is 1.1

You need to know this URL when looking up the API documentation and making requests to the API endpoints.

For example, the URL for a request to get all work items in the tenancy might look like:

• https://tenancy1.testserver01.yourorganization.com/HdaApi/rest/v1.1/WorkItems

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
namespace HotDocsAdvanceApiExamples
{
    public class UserRequest
    {
        public async Task<HttpStatusCode> CreateUser(string token)
        {
            // Create the 'create user' request  
            var userId = Guid.NewGuid();
            var request = CreateHttpRequestMessage(userId);
            //Send create user request to Advance
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                var response = await client.SendAsync(request);                
                return response.StatusCode;
            }
        }
        private HttpRequestMessage CreateHttpRequestMessage(Guid userId)
        {
            // Create the request for the 'create user' API endpoint
            var createUserUrl = string.Format("https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/Users/{0}", userId);

            return new HttpRequestMessage
            {
                RequestUri = new Uri(createUserUrl),
                Method = HttpMethod.Post,
                Content = GetRequestContent()
            };
        }
        private StringContent GetRequestContent()
        {
            // Generate the JSON request body required by the 'create user' method
            var json = "{ 'firstName': 'Emma', 'lastName': 'MacDiarmid', 'emailAddress': 'emma.macdiarmid@example.com', 
	'roles': [ 'SiteAdministrator'	], 'sendEmail': true }";
            return new StringContent(json, Encoding.UTF8, "application/json");
        }
    }
}

You can view the latest reference documentation for the Advance API at https://yourorganization.com/HdaApi/rest/documentation/index.html, where yourorganization.com is the domain under which your Advance deployment is located.