Set Up Guide

1. Open a web browser.
2. Navigate to the application using the following URL:
   https://{tenancymoniker}.hotdocsadvance.com/auth
   Where tenancymoniker is replaced with the tenancy you want to access.
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.hotdocsadvance.com/Auth/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:

• https://{tenancyMoniker}.hotdocsadvance.com/api/rest/v{apiVersionNumber}/

Where:

• tenancyMoniker – the name of the Advance tenancy against which you are making requests; for example, tenancy1
• 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.hotdocsadvance.com/api/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.hotdocsadvance.com/api/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 documentation for the Advance API at http://hotdocsadvance.com/api/rest/documentation/index.html