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:

• 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.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.hotdocsadvance.com/api/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 documentation for the Advance API at http://hotdocsadvance.com/api/rest/documentation/index.html