Frontend authentication

The <pdf-application> component will try to obtain an access token by making a POST request to the relative URL /api/sessions.

Notice

You are responsible for providing this endpoint and returning the access token to the PDF viewer. It must be hosted on the same host that serves your frontend.

You in turn obtain the access token by making a POST request to <api-base-url>/v1/sessions with the public-private key pair as the request data. <api-base-url> is either the unopdf api url (https://api.unopdf.com/api) for the hosted solution or the url of your self-hosted api. (See Self hosting for more information).

The code samples below assume that you have set environment variables for the UNOPDF_PRIVATE_KEY, UNOPDF_PUBLIC_KEY and UNODPDF_API_URL.

shell

curl -X POST \
  -H "Content-Type: application/json" \
  -d "{ \"privatekey\": \"$UNOPDF_PRIVATE_KEY\", \"publickey\": \"$UNOPDF_PUBLIC_KEY\" }" \
  $UNOPDF_API_URL/v1/sessions

c#

using System.Text;
using System.Text.Json;

var apiUrl = Environment.GetEnvironmentVariable("UNOPDF_API_URL");
var publicKey = Environment.GetEnvironmentVariable("UNOPDF_PUBLIC_KEY");
var privateKey = Environment.GetEnvironmentVariable("UNOPDF_PRIVATE_KEY");

var client = new HttpClient();

try
{
    using StringContent jsonContent = new(
        JsonSerializer.Serialize(new
        {
            privatekey = privateKey,
            publickey = publicKey,
        }),
        Encoding.UTF8,
        "application/json");
    using var response = await client.PostAsync($"{apiUrl}/v1/sessions", jsonContent);
    response.EnsureSuccessStatusCode();
    var responseBody = await response.Content.ReadAsStringAsync();

    Console.WriteLine(responseBody);
}
catch (HttpRequestException e)
{
    Console.WriteLine("Error calling UnoPdf API: {0}", e.Message);
}

js

  const api_url = process.env.UNOPDF_API_URL;
  const privatekey = process.env.UNOPDF_PRIVATE_KEY;
  const publickey = process.env.UNOPDF_PUBLIC_KEY;

  const method = "POST";
  const headers = { "Content-Type": "application/json" };
  const body = JSON.stringify({ publickey, privatekey });

  const response = await fetch(`${api_url}/v1/sessions`, {
    method,
    headers,
    body,
  });

  if (response.status !== 200) {
    throw new Error(`Error getting token from UnoPdf API`);
  }

  const json = await response.json();
  if (typeof json !== "string") {
    throw new Error(`Unexpected response from UnoPdf API: ${json}`);
  }

  return json;

This scheme ensures that your credentials are not exposed to the browser. The following illustrates this sequence:

null

During development you may skip providing your backend by calling <api-base-url>/sessions directly as illustrated by the following sequence:

null

Once the access token has been obtained, it will be included in all subsequent requests to the PDF web API. If the access token expires, it will be obtained again using the same sequence.

Backend authentication

If you want to call the Document API directly from your server application you don't need to request a token for authentication purposes.

You can directly use your public key and private key to sign requests using HMAC.

In order to do so you need to provide an Authorization header with a SharedKey. The Sharedkey contains two parts:

1. your public key
2. a payload that is signed with your private key. The payload exists of the http method or verb (e.g. GET or POST), the current timestamp in RFC 1123 format (e.g. Tue, 19 Dec 2023 09:38:33 GMT) and the path of the endpoint that you want to access (e.g. /v1/files). These three parts are seperated by newlines. This signed payload is called a digest.

Before we can pass this digest in the header we have to make sure that it is 'urlsafe'. This means stripping any = characters and replaceing + and / with -.

Finally the Authorization header looks like this Authorization: SharedKey: ${public_key}:${urlsafe_digest}.

If you are using the Dotnet API Client you do not need to worry about the HMAC signing. The client takes care of that. You only have to provide your public key and private key:

// requires nuget package TallComponents.UnoPdf.Client
using TallComponents.UnoPdf.Client;

var client = new ApiClientFactory(PublicKey, PrivateKey)
  .CreateClient();

var documents = await client.GetLocalDocumentsAsync();

The code samples sections has examples for how to generate the HMAC headers in Python and Nodejs