Connect to a tdx Volt

The tdx Volt command line interface (CLI) and all client libraries make use of a JSON object stored in a local file to persist the details of a client connection to the Volt.

A full description of the client connection JSON format and how to obtain or create one can be found in the connection section.

api

The VoltAPI.Authenticate API enables clients to authenticate on a Volt and obtain credentials for subsequent API calls.

cli

Use the auth command.

./volt auth -help

To authenticate on a Volt with the DID did:volt:a06e10d1-3fa4-445a-948f-7e7c5ee36262 use the following command:

./volt auth did:volt:a06e10d1-3fa4-445a-948f-7e7c5ee36262 "Bob"

By default, the configuration details will be stored in a file called volt.config.json in the current working directory. You can specify a different file using the -c switch:

./volt auth did:volt:a06e10d1-3fa4-445a-948f-7e7c5ee36262 "Bob" -c bob.config.json

You can use the discovery URL of the Volt instead of the DID:

./volt auth https://acme.com "Bob" -c bob.config.json

javascript

Use the Authenticate API, the response will contain the generated credentials on success.

grpc

It’s not normally necessary to explicitly use the Authenticate API when using the grpc client library, as the library will automatically authenticate if required when initialise is called.

It’s worth noting that the initialise call will not return until either a ‘permit’ or ‘deny’ decision is received from the Volt. This means that the initialise call will block if there is a ‘prompt’ decision, which will occur if the Volt is configured to require user interaction for authentication.

import { VoltClient } from "@tdxvolt/volt-client-grpc";
import grpc from "@grpc/grpc-js";

// This is the path where we'd like to store the generated configuration.
const configPath = "./volt.config.json";

const voltConfig = {};

// This is the name we'd like to use for our client.
voltConfig.client_name = "Alice";

// This is the DID of the Volt we'd like to connect to.
voltConfig.volt = "did:volt:a06e10d1-3fa4-445a-948f-7e7c5ee36262";

// Alternatively, you can use the URL of the Volt instead of the DID.
voltConfig.volt = "http://192.168.1.195:49824";

const voltClient = new VoltClient(grpc);

voltClient
  .initialise(configPath, voltConfig)
  .then((response) => {
    console.log(response);
  })
  .catch((err) => {
    console.error(err.message);
  })
  .finally(() => {
    console.log("finished");
  });

Once the client has been initialised, the configuration will be stored in the file specified by configPath. The next time the client is initialised, the configuration will be read from this file.

If you’d rather manage the persistence of the configuration yourself, you can pass a configuration object directly to the initialise method rather than a file path:

import { VoltClient } from "@tdxvolt/volt-client-grpc";
import grpc from "@grpc/grpc-js";

// Initialise or load the configuration here.
const voltConfig = {};

// This is the name we'd like to use for our client.
voltConfig.client_name = "Alice 2";

// This is the DID of the Volt we'd like to connect to.
voltConfig.volt = "did:volt:a06e10d1-3fa4-445a-948f-7e7c5ee36262";

const voltClient = new VoltClient(grpc);

voltClient
  .initialise(voltConfig)
  .then((response) => {
    // Persist the configuration here.
    console.log(response);
  })
  .catch((err) => {
    console.error(err.message);
  })
  .finally(() => {
    console.log("finished");
  });

web

  const sub = client.Authenticate({
    client_name: "Bob",
    "public_key": "<PEM encoded key>"
  });

C++

examples coming soon...