API Setup Guide

1. Log into the HotDocs Advance Auth application.
2. Click the Manage API 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
        {
        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();
        }
    }
}

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, e.g. v1.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.Net.Http.Json;
using System.Text;
using System.Threading.Tasks;
namespace HotDocsAdvanceApiExamples
{
    public class UserRequest
    {
        public static async Task<HttpStatusCode> CreateUserAsync(string token)
        {
            using var client = new HttpClient();
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
           
            var userId = Guid.NewGuid();
            var request = new HttpRequestMessage
            {
                RequestUri = new Uri($"https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/Users/{userId}"),
                Method = HttpMethod.Post,
                Content = JsonContent.Create(new
                {
                    FirstName = "Emma",
                    LastName = "MacDiarmid",
                    EmailAddress = "emma.macdiarmid@example.com",
                    Roles = new[] { "SiteAdministrator" },
                    SendEmail = true
                })
            };
           
            var response = await client.SendAsync(request);
            return response.StatusCode;
        }
    }
}

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.