RelayAPI

Top

GetVoltEndpoint()

Retrieve the list of Volts available on the Relay Volt.

Request: GetVoltEndpointRequest
Response: GetVoltEndpointResponse

Tunnel()

This is the actual tunnel stream.

Note although this API semantically describes the tunnel stream, it isn't actually implemented anywhere. It is used by client libraries to easily serialise tunnel payloads.

Request: streaming .tdx.volt_api.volt.v1.RemoteRequest
Response: streaming .tdx.volt_api.volt.v1.RemoteResponse

CloudTunnel()

This is the tunnel stream for cloud-based tunnels.

Request: streaming TunnelRequest
Response: streaming TunnelResponse

GetVoltEndpointRequest

FieldTypeDescription
owner_idstring

Filter on the owning identity.

volt_idstring

Filter on volt id.

GetVoltEndpointResponse

FieldTypeDescription
statustdx.volt_api.volt.v1.Status

endpointtdx.volt_api.volt.v1.VoltEndpoint repeated

TunnelControl

FieldTypeDescription
startTunnelStart

add_serviceTunnelServiceControl

remove_serviceTunnelServiceControl

TunnelRequest

FieldTypeDescription
pingtdx.volt_api.volt.v1.RemotePing

controlTunnelControl

method_payloadtdx.volt_api.volt.v1.MethodPayload

method_endtdx.volt_api.volt.v1.MethodEnd

http_responsetdx.volt_api.volt.v1.HttpResponse

TunnelResponse

FieldTypeDescription
pingtdx.volt_api.volt.v1.RemotePing

method_invoketdx.volt_api.volt.v1.MethodInvoke

method_payloadtdx.volt_api.volt.v1.MethodPayload

method_endtdx.volt_api.volt.v1.MethodEnd

http_requesttdx.volt_api.volt.v1.HttpRequest

TunnelServiceControl

FieldTypeDescription
resource_idstring

service_namestring

service_descriptiontdx.volt_api.volt.v1.ServiceDescription

TunnelStart

FieldTypeDescription
preferred_portuint32

addressstring

public_keystring

fingerprintstring

ca_pemstring

volt_versionstring

HttpInvoke

FieldTypeDescription
hoststring

portint32

methodstring

urlstring

versionstring

headersHttpInvoke.HeadersEntry repeated

bodybytes

HttpInvoke.HeadersEntry

FieldTypeDescription
keystring

valuestring

HttpPayload

FieldTypeDescription
chunkbytes

endbool

errorint32

HttpRequest

FieldTypeDescription
iduint64

http_invokeHttpInvoke

http_payloadHttpPayload

HttpResponse

FieldTypeDescription
iduint64

http_payloadHttpPayload

MethodEnd

FieldTypeDescription
iduint64

endedbool

errorstring

error_codeint32

MethodInvoke

FieldTypeDescription
iduint64

service_idstring

method_namestring

method_typeMethodType

requestbytes

json_requeststring

MethodPayload

FieldTypeDescription
iduint64

payloadbytes

json_payloadstring

RemotePing

FieldTypeDescription
timestampuint64

RemoteRequest

FieldTypeDescription
pingRemotePing

method_payloadMethodPayload

method_endMethodEnd

http_responseHttpResponse

RemoteResponse

FieldTypeDescription
pingRemotePing

method_invokeMethodInvoke

method_payloadMethodPayload

method_endMethodEnd

http_requestHttpRequest

MethodType

NameNumberDescription
METHOD_TYPE_UNKNOWN0

METHOD_TYPE_UNARY1

METHOD_TYPE_CLIENT_STREAM2

METHOD_TYPE_SERVER_STREAM3

METHOD_TYPE_BIDI4

Status

FieldTypeDescription
codeint32

A simple error code that can be easily handled by the client.

Mirrors the grpc StatusCode enum, 0 => OK

messagestring

A developer-facing human-readable error message in English. It should both explain the error and offer an actionable resolution to it.

descriptionstring

Long form error description.

Access

FieldTypeDescription
idstring

resource_idstring

The resource being accessed.

resource_namestring

A human-readable short identifier of the resource.

resource_ownerstring

The identity that owns the resource.

resource_kindstring repeated

The kind of resource.

identity_didstring

The identity attempting access.

credential_lookupstring

The JSON path array for looking up verifiable credentials.

identity_namestring

A human-readable short identifier of the subject.

identity_kindstring repeated

The kind of identity.

accessstring

Requested access.

extrastring

Optional extra data.

decisionPolicyDecision

Assigned decision.

recursivebool

request_timeint64

Time at which the request was made.

decision_timeint64

Time at which the decision was taken.

request_countuint32

Counter of number times this access was requested.

AttributeValue

Attribute value will be one of the following fields, depending on the data type.

FieldTypeDescription
stringstring

integerint64

realdouble

booleanbool

bytesbytes

Identity

A Volt identity encompasses a Resource and a set of identity aliases.

FieldTypeDescription
resourceResource

aliasIdentityAlias repeated

IdentityAlias

FieldTypeDescription
iduint32

The alias id.

identity_didstring

The corresponding identity id.

aliasstring

The actual alias, e.g. a common name or key fingerprint.

public_keystring

This will only be populated if alias_type == tdx:public-key

private_keystring

This will only be populated if alias_type == tdx:public-key, and the key is stored in the Volt.

alias_typestring

The alias type, for example public key, email, phone number etc.

issuer_idstring

The identity that issued this alias.

authenticatePolicyDecision

Indicates if this alias has an authenticate policy decision assigned.

descriptionstring

Optional description of this alias.

MethodDescription

Internal use only.

FieldTypeDescription
pathstring

client_streamingbool

server_streamingbool

ProtoFile

Describes a single protobuf file for use in ServiceDescription.

FieldTypeDescription
file_pathstring

The path name of the proto file, relative to the 'root' of the namespace, e.g. "tdx/volt_api/volt/v1/volt.proto".

protobufstring

The actual protobuf file contents.

service_namestring repeated

Optional - the service(s) contained in this protobuf file, if omitted here they will be loaded dynamically from the protobuf.

ProxyConnection

Represents an outbound connection from a Volt to a remote service that will act as a proxy for that Volt.

This enables Volts to bypass firewall and NATs.

Example - connection from a Volt to a Relay Volt running on the public internet, such as tdxvolt.com

FieldTypeDescription
idstring

Unique connection id.

namestring

A human-readable name for the connection.

addressstring

The remote address of the proxy service.

ca_pemstring

The certificate authority of the proxy service.

enabledbool

Indicates this connection is enabled.

connectedbool

Indicates this connection is currently in use.

enable_http_proxybool

Indicates that this connection will handle HTTP proxying as well as GRPC.

disable_volt_apibool

Set to indicate the Volt API itself is not automatically exposed to the connection.

challengestring

Optional challenge that can be presented in the authentication request.

target_idstring

The id of the target Volt that this connection is bound to.

sync_did_registrybool

Indicates that this connection hosts a DID registry that we should synchronise with.

did_registry_sync_iduint64

The id of the last DID registry operation that was synchronised.

sync_vc_registrybool

Indicates that this connection hosts a DID registry that we should synchronise with.

vc_registry_sync_timestampuint64

The timestamp of the last VC registry operation that was synchronised.

session_idstring

certificatestring

Resource

The core Resource metadata schema.

FieldTypeDescription
idstring

The globally unique resource id.

descriptionstring

Optional description.

namestring

Human-readable resource name.

share_modeShareMode

Not in use.

volt_idstring

The id of the Volt that hosts this resource.

service_descriptionServiceDescription

Optional description of any services exposed by this resource.

attributeResourceAttribute repeated

Attributes assigned to the resource.

platform_versionVersion

The version of the platform.

versionuint64

The resource version.

ownerstring

The identity of the resource owner.

createduint64

Creation timestamp, milliseconds since epoch.

modifieduint64

Last modification timestamp, milliseconds since epoch.

statusResourceStatus

Not in use.

kindstring repeated

The taxonomy of the resource.

online_statusOnlineStatus

The online status.

For most kinds of resource this indicates that the server hosting the resource is online, the exception being identity resources, in which case the status reflects whether or not the identity has a live connection.

All built-in resources are hosted by the Volt itself and are therefore always online when the Volt is running.

Resources hosted by external servers are online if the server itself is online and has registered the resource as online using `setServiceStatus`.

sizeuint64

The size of the resource store in bytes.

storestring

The path to the resource store.

aliasstring repeated

Alias(es) that can be used to refer to the resource rather than the id.

Each alias must be unique to the Volt, this is enforced by the API.

No format restrictions are currently applied to alias, but this may change in future, for the time being it makes sense to stick to alphanumeric characters and '_' or '-'.

content_hashstring

The hash of the resource content contained in the store.

childResource repeated

Not yet supported.

ResourceAttribute

A resource attribute enables storing arbitrary data associated with a resource.

FieldTypeDescription
iduint32

attribute_idstring

resource_idstring

data_typeAttributeDataType

valueAttributeValue repeated

ServiceDescription

Describes a Volt service.

FieldTypeDescription
host_typeServiceHostType

The configuration used by the host of this service.

host_client_idstring

The identity of the client that is exposing the service.

For example, if a third party is exposing a database service via a Volt, it will first authenticate and obtain a client DID and credentials in order to be able to create service resource(s).

Any resources that are owned by this client will be marked as online if the client itself is online, i.e. has a live connection to the Volt.

This will be empty if the service is a built-in Volt service.

host_service_idstring

The id of the resource that holds the protobuf definition for this resource.

For example, if a third party is exposing a database service via a Volt, it will create a service resource that holds details of the protobuf methods exposed by the service.

For built-in services, i.e. those hosted by the Volt, this will set to the Volt id.

host_addressstring

The address of the grpc server hosting this service.

Only relevant to grpc-hosted services.

host_ca_pemstring

The certificate authority (chain) that signed the service server certificate.

This is only relevant to grpc-hosted services.

host_public_keystring

The public key of the service host, which is used to encrypt payloads.

This may change as the service comes and goes online.

host_connection_idstring

The connection id currently used to host this service.

host_session_idstring

Internal use only.

discoverableDiscoveryMode

The discovery mode.

ping_timestampint64

The ping timestamp of the server hosting this service.

proto_fileProtoFile repeated

The protobuf definitions of the APIs exposed by this service.

service_apistring repeated

The fully qualified names of the protobuf services, for example tdx.volt_api.webcam.v1.WebcamControlAPI.

methodMethodDescription repeated

Internal use only.

Session

FieldTypeDescription
idstring

identity_didstring

identity_namestring

ipstring

createduint64

modifieduint64

expiresuint64

credentialSessionCredential repeated

originstring

statusSessionStatus

SessionCredential

FieldTypeDescription
iduint32

The alias id.

session_idstring

The corresponding session id.

credential_typestring

The credential type, for example public key, verifiable credential, challenge etc.

descriptionstring

Optional description of this credential.

vc_idstring

The id of the verifiable credential, if the credential type is volt:vc-claim.

vc_jsonstring

The verifiable credential in JSON format, if the credential type is volt:vc-claim.

vc_subject_idstring

The subject id extracted from the `vc_json` field.

vc_issuer_idstring

The issuer id extracted from the `vc_json` field.

vc_typestring

The comma-separated type(s) extracted from the `vc_json` field.

challengestring

The challenge string, if the credential type is volt:challenge.

key_fingerprintstring

The key fingerprint, if the credential type is volt:public-key.

public_keystring

The PEM-encoded public key, if the credential type is volt:public-key.

private_keystring

Optional PEM-encoded private key, if the credential type is volt:public-key. Only used for ephemeral REST-base sessions created dynamically after OTP authentication.

extrastring

Type-specific extra data stored with the credential.

extra_2string

More type-specific data stored with the credential.

Version

Using `major` and `minor` here upsets the GNU C Library, so we add a `version_` prefix.

FieldTypeDescription
version_majoruint32

version_minoruint32

version_patchuint32

VoltEndpoint

FieldTypeDescription
idstring

The globally unique Volt id.

display_namestring

Human-readable name of the Volt.

local_addressstring

The actual host/ip the volt is physically running on (might be a local ip if behind firewall).

http_addressstring

The address of the endpoint HTTP server.

relay_addressstring

The global (Relay) address of the volt. Any given volt may be advertising on more than one Relay instance. The value given here will depend on the Relay instance that handled the endpoint query response.

relay_ca_pemstring

The root certificate of the Relay instance referred to in `relay_address`.

ca_pemstring

The self-signed certificate used by the volt to sign client certificates.

public_keystring

The Volt public key in PEM format.

fingerprintstring

The base58 fingerprint of the Volt public key.

online_statusOnlineStatus

The online status of the Volt.

has_relaybool

Indicates that this Volt acts as a Relay.

api_versionVersion

The API version supported by the endpoint.

descriptionstring

Optional description of the endpoint.

did_registrystring repeated

The list of DID registries that this Volt trusts.

VoltParameters

Encapsulates the various Volt parameters that are configurable by the Volt owner.

FieldTypeDescription
idstring

namestring

The name of the Volt.

descriptionstring

Human-readable description of the Volt.

db_driverstring

The database driver in use.

locationstring

The local file path location of the Volt storage.

key_strategystring

The key strategy in use, this determines how the root key is stored.

key_idstring

The identifier for the key, the semantics depend on the key strategy in use.

ca_pemstring

The Volt certificate authority.

cert_pemstring

The Volt API server certificate.

fixed_hoststring

Optional hostname of the Volt if using DNS or a static IP address, e.g. tdxvolt.com

grpc_portint32

Port to use for hosting the Volt management service.

http_portint32

Port to use for hosting the Volt grpc service.

http_key_pathstring

The Volt http server key file path.

http_cert_pathstring

The Volt http server certificate file path.

http_ca_pathstring

The Volt http server certificate authority chain file path.

discoverablebool

Indicates the Volt will be discoverable by clients using the discovery api.

authenticate_challengestring

Optional challenge code that can be used aid in the process of authenticating clients.

require_authenticate_challengebool

Indicates that clients must present the correct challenge code in order to be able to authenticate.

confirm_stopbool

Internal use only.

auto_startbool

Internal use only.

enable_messagingbool

Internal use only.

has_relaybool

Set to indicate this Volt acts as a Relay.

This means this Volt can act as a proxy for other Volts (or in fact any client) that connect to it.

relay_openbool

Set to run the Relay open to any client, i.e. clients can utilise the Relay without first authenticating.

enable_http_serverbool

Determines if the Volt HTTP server is enabled.

http_server_securebool

Determines whether the HTTP server employs TLS.

enable_http_forwardingbool

Determines whether the HTTP server supports forwarding.

enable_http_apibool

Determines if the Volt REST API is exposed via the HTTP server.

enable_websocket_apibool

Determines if the Volt Websocket API is exposed via the HTTP server.

addressstring

The hostname:port at which the Volt API is currently running.

encrypt_file_storebool

Set to indicate the Volt file store is encrypted.

connection_idstring

This is a unique connection id.

Indicates that these parameters refer to a connection to a remote Volt rather than a local Volt.

relay_ca_pemstring

The certificate authority of the Relay if this is a remote connection via a Relay.

http_address_overridestring

Optional override of the http address, rather than using the default of fixed_host:http_port.

This is useful if the Volt is behind a firewall or NAT, and the http server is listening on a different port

from 80 or 443 but this is hidden by the proxy. For example, if the `fixed_host` is `coreid.com` and http server is

listening on 2115, but the proxy is forwarding 443 to 2115, then the http_address_override would be set to

`https://coreid.com`.

aliasstring

An optional alias that can be used to refer to the Volt rather than the `id` field.

This alias must be unique within the scope of the Battery in which the Volt is stored.

versionVersion

The runtime version this Volt is running.

approve_on_challengebool

If set, indicates that any client that provides the correct challenge during authentication will automatically be approved to access the Volt.

approve_on_didbool

If set, indicates that any client that proves ownership of a DID known to the Volt will automatically be approved to access the Volt.

enable_did_registrybool

If set, indicates that clients can register DIDs with this Volt.

did_registrystring repeated

Zero or more URLs of trusted peer DID registries.

enable_outbound_smtpbool

If set, enables outbound SMTP.

outbound_smtp_hoststring

The SMTP host to use for sending emails.

outbound_smtp_portuint32

The SMTP port to use for sending emails.

outbound_smtp_userstring

The SMTP username to use for sending emails.

outbound_smtp_passwordstring

The SMTP password to use for sending emails.

enable_anonymous_createbool

If set, enables sessions that authenticate using credentials rather than a DID to create resources in the 'anonymous' system folder.

catch_all_auth_decisionPolicyDecision

The decision to apply to all authentication requests that do not match any other policy.

The default is PROMPT.

enable_policy_cachebool

If set, enables caching of policy decisions.

enable_terminalbool

If set, enables the terminal API.

start_timeuint64

The time at which the Volt was started.

AttributeDataType

Attribute data types.

NameNumberDescription
ATTRIBUTE_DATA_TYPE_UNKNOWN0

ATTRIBUTE_DATA_TYPE_STRING1

ATTRIBUTE_DATA_TYPE_INTEGER2

ATTRIBUTE_DATA_TYPE_REAL3

ATTRIBUTE_DATA_TYPE_BOOLEAN4

ATTRIBUTE_DATA_TYPE_BYTES5

ATTRIBUTE_DATA_TYPE_IDENTITY100

ATTRIBUTE_DATA_TYPE_RESOURCE101

DiscoveryMode

NameNumberDescription
DISCOVERY_MODE_UNKNOWN0

DISCOVERY_MODE_TRUSTED1

Only local identities with explicit policy PERMIT can discover.

DISCOVERY_MODE_PUBLIC2

Any bound local identity can discover.

DISCOVERY_MODE_TRUSTED_GLOBAL3

Only identities with explicit policy PERMIT can discover, and the service will be available to local and non-local (Relayed) clients.

DISCOVERY_MODE_PUBLIC_GLOBAL4

Any bound identity can discover, and the service will be available to local and non-local (Relayed) clients.

OnlineStatus

NameNumberDescription
ONLINE_STATUS_UNKNOWN0

ONLINE_STATUS_ONLINE1

ONLINE_STATUS_OFFLINE2

PolicyDecision

@todo currently this must align with AuthorisationDecision enum in policy library, but some of the values are irrelevant outside of the public API so we need a public-facing enum and some translation.

NameNumberDescription
POLICY_DECISION_UNKNOWN0

POLICY_DECISION_PROMPT1

POLICY_DECISION_PERMIT2

POLICY_DECISION_DENY3

POLICY_DECISION_INDETERMINATE4

POLICY_DECISION_NOT_APPLICABLE5

POLICY_DECISION_APPLICABLE6

POLICY_DECISION_PENDING7

ResourceStatus

Not used ATM.

NameNumberDescription
RESOURCE_STATUS_UNKNOWN0

RESOURCE_STATUS_LIVE1

RESOURCE_STATUS_INACTIVE2

RESOURCE_STATUS_DELETED999

SecureMode

NameNumberDescription
SECURE_MODE_UNKNOWN0

SECURE_MODE_INSECURE1

SECURE_MODE_TLS2

ServiceHostType

NameNumberDescription
SERVICE_HOST_TYPE_UNKNOWN0

SERVICE_HOST_TYPE_BUILTIN1

A built-in service hosted by the Volt.

SERVICE_HOST_TYPE_SERVER2

A service hosted by a grpc server other than the Volt.

SERVICE_HOST_TYPE_RELAYED3

A service hosted by a Volt client via a relay connection, i.e. the service is not exposed by a server as such, rather a Volt client implements the service and a Volt acts as a proxy, calling back to the client to implement the methods.

SessionStatus

NameNumberDescription
SESSION_STATUS_UNKNOWN0

SESSION_STATUS_PENDING1

SESSION_STATUS_LIVE2

SESSION_STATUS_EXPIRED3

SESSION_STATUS_REVOKED4

SESSION_STATUS_REJECTED5

ShareMode

Not used ATM.

NameNumberDescription
SHARE_MODE_UNKNOWN0

SHARE_MODE_TRUSTED1

SHARE_MODE_PUBLIC_READ2

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)