Getting a JSON Web Token#

The TrueSign API uses a JSON Web Token (JWT) to authorize client calls with the Bearer authentication scheme. A client is an Envelope Type configured in the Admin View of the TrueSign application. To get a JWT, you should have a client id and a client secret.

The authorization token is retrieved by making an http post towards the /auth endpoint of the API, and the body of this request must have the client_id and client_secret as parameters. If the correct credentials were provided, TrueSign will return an API token object, containing the token itself and its expiration datetime in UTC. The authorization token must be present as an authorization header of the Bearer schema for all calls made towards the TrueSign API, excluding the /auth endpoint.

The example below shows a C# method that returns the token as string when called.

Note: Replace my_client_id and my_client_secret with the correct values.

public static string GetToken()
{
    try
    {
        //Create a new HttpClient (using System.Net.Http)
        using(var httpClient = new HttpClient())
        {
            var clientId = "my_client_id"; //Replace with your own Client ID
            var clientSecret = "my_client_secret"; //Replace with your own Client Secret

            //Set the base API address for the client
            httpClient.BaseAddress = new Uri("https://api.truesign.com/v1/");

            //Create the body with the client credentials
            var json = JsonConvert.SerializeObject(new Dictionary<string, string>() { { "client_id", clientId }, { "client_secret", clientSecret } });
            var body = new StringContent(json, Encoding.UTF8, "application/json");

            //Make a POST call to the authentication endpoint to receive a JWT
            var response = httpClient.PostAsync("auth", body).Result;

            //Ensure the call did not error out. If it did error out, then this will throw an exception.
            response.EnsureSuccessStatusCode();

            //Read the JWT from the response.
            var tokenStr = response.Content.ReadAsStringAsync().Result;
            dynamic tokenObject = JsonConvert.DeserializeObject(tokenStr);

            //Print out the token received and its expiry timestamp
            Console.WriteLine("Token: " + tokenObject.Token);
            Console.WriteLine("Expires: " + tokenObject.Expires_UTC);

            return tokenObject.Token.ToString();
        }
    }
    catch
    {
        throw;
    }
}

If successful, the method will return a string that looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

We will use this JWT for every call made to the TrueSign API. The issued token expires in 7 days from the time it was issued. Reusing the token is recommended, but not required. If you are reusing an HttpClient object, you may attach the token to the clients header list:

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

Calling the API#

Once you have obtained a token from the authentication endpoint of the TrueSign API, you may call the other methods of the API. Here is a simple example in C# when calling the Me endpoint of the Authentication controller to receive information about the authenticated client:

public static string GetEnvelopeTypeInfo(string token)
{
    try
    {
        //Create a new HttpClient (using System.Net.Http)
        using(var httpClient = new HttpClient())
        {
            //Set the base address for the client
            httpClient.BaseAddress = new Uri("https://api.truesign.com/v1/");
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

            //Make a GET call to the 'Me' endpoint to receive information about the authenticated client
            var response = httpClient.GetAsync("auth/me", body).Result;

            //Ensure the call did not error out. If it did error out, then this will throw an exception.
            response.EnsureSuccessStatusCode();

            //Read the JWT from the response.
            var client = response.Content.ReadAsStringAsync().Result;
            Console.WriteLine("Client info: " + client);

            return token;
        }
    }
    catch
    {
        throw;
    }
}

Note: All responses returned by the API are in JSON format. Use Newtonsoft.Json to parse the API's responses when using C#.