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...