RelayAPI
TopGetVoltEndpoint()
Retrieve the list of Volts available on the Relay Volt.
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.
CloudTunnel()
This is the tunnel stream for cloud-based tunnels.
GetVoltEndpointRequest
Field | Type | Description |
owner_id | string | Filter on the owning identity. |
volt_id | string | Filter on volt id. |
GetVoltEndpointResponse
Field | Type | Description |
status | tdx.volt_api.volt.v1.Status | |
endpoint | tdx.volt_api.volt.v1.VoltEndpoint repeated |
TunnelControl
Field | Type | Description |
start | TunnelStart | |
add_service | TunnelServiceControl | |
remove_service | TunnelServiceControl |
TunnelRequest
Field | Type | Description |
ping | tdx.volt_api.volt.v1.RemotePing | |
control | TunnelControl | |
method_payload | tdx.volt_api.volt.v1.MethodPayload | |
method_end | tdx.volt_api.volt.v1.MethodEnd | |
http_response | tdx.volt_api.volt.v1.HttpResponse |
TunnelResponse
Field | Type | Description |
ping | tdx.volt_api.volt.v1.RemotePing | |
method_invoke | tdx.volt_api.volt.v1.MethodInvoke | |
method_payload | tdx.volt_api.volt.v1.MethodPayload | |
method_end | tdx.volt_api.volt.v1.MethodEnd | |
http_request | tdx.volt_api.volt.v1.HttpRequest |
TunnelServiceControl
Field | Type | Description |
resource_id | string | |
service_name | string | |
service_description | tdx.volt_api.volt.v1.ServiceDescription |
TunnelStart
Field | Type | Description |
preferred_port | uint32 | |
address | string | |
public_key | string | |
fingerprint | string | |
ca_pem | string | |
volt_version | string |
HttpInvoke
Field | Type | Description |
host | string | |
port | int32 | |
method | string | |
url | string | |
version | string | |
headers | HttpInvoke.HeadersEntry repeated | |
body | bytes |
HttpInvoke.HeadersEntry
Field | Type | Description |
key | string | |
value | string |
HttpPayload
Field | Type | Description |
chunk | bytes | |
end | bool | |
error | int32 |
HttpRequest
Field | Type | Description |
id | uint64 | |
http_invoke | HttpInvoke | |
http_payload | HttpPayload |
HttpResponse
Field | Type | Description |
id | uint64 | |
http_payload | HttpPayload |
MethodEnd
Field | Type | Description |
id | uint64 | |
ended | bool | |
error | string | |
error_code | int32 |
MethodInvoke
Field | Type | Description |
id | uint64 | |
service_id | string | |
method_name | string | |
method_type | MethodType | |
request | bytes | |
json_request | string |
MethodPayload
Field | Type | Description |
id | uint64 | |
payload | bytes | |
json_payload | string |
RemotePing
Field | Type | Description |
timestamp | uint64 |
RemoteRequest
Field | Type | Description |
ping | RemotePing | |
method_payload | MethodPayload | |
method_end | MethodEnd | |
http_response | HttpResponse |
RemoteResponse
Field | Type | Description |
ping | RemotePing | |
method_invoke | MethodInvoke | |
method_payload | MethodPayload | |
method_end | MethodEnd | |
http_request | HttpRequest |
MethodType
Name | Number | Description |
METHOD_TYPE_UNKNOWN | 0 | |
METHOD_TYPE_UNARY | 1 | |
METHOD_TYPE_CLIENT_STREAM | 2 | |
METHOD_TYPE_SERVER_STREAM | 3 | |
METHOD_TYPE_BIDI | 4 |
Status
Field | Type | Description |
code | int32 | A simple error code that can be easily handled by the client. Mirrors the grpc StatusCode enum, 0 => OK |
message | string | A developer-facing human-readable error message in English. It should both explain the error and offer an actionable resolution to it. |
description | string | Long form error description. |
Access
Field | Type | Description |
id | string | |
resource_id | string | The resource being accessed. |
resource_name | string | A human-readable short identifier of the resource. |
resource_owner | string | The identity that owns the resource. |
resource_kind | string repeated | The kind of resource. |
identity_did | string | The identity attempting access. |
credential_lookup | string | The JSON path array for looking up verifiable credentials. |
identity_name | string | A human-readable short identifier of the subject. |
identity_kind | string repeated | The kind of identity. |
access | string | Requested access. |
extra | string | Optional extra data. |
decision | PolicyDecision | Assigned decision. |
recursive | bool | |
request_time | int64 | Time at which the request was made. |
decision_time | int64 | Time at which the decision was taken. |
request_count | uint32 | Counter of number times this access was requested. |
AttributeValue
Attribute value will be one of the following fields, depending on the data type.
Field | Type | Description |
string | string | |
integer | int64 | |
real | double | |
boolean | bool | |
bytes | bytes |
Identity
A Volt identity encompasses a Resource and a set of identity aliases.
Field | Type | Description |
resource | Resource | |
alias | IdentityAlias repeated |
IdentityAlias
Field | Type | Description |
id | uint32 | The alias id. |
identity_did | string | The corresponding identity id. |
alias | string | The actual alias, e.g. a common name or key fingerprint. |
public_key | string | This will only be populated if alias_type == tdx:public-key |
private_key | string | This will only be populated if alias_type == tdx:public-key, and the key is stored in the Volt. |
alias_type | string | The alias type, for example public key, email, phone number etc. |
issuer_id | string | The identity that issued this alias. |
authenticate | PolicyDecision | Indicates if this alias has an authenticate policy decision assigned. |
description | string | Optional description of this alias. |
MethodDescription
Internal use only.
Field | Type | Description |
path | string | |
client_streaming | bool | |
server_streaming | bool |
ProtoFile
Describes a single protobuf file for use in ServiceDescription.
Field | Type | Description |
file_path | string | The path name of the proto file, relative to the 'root' of the namespace, e.g. "tdx/volt_api/volt/v1/volt.proto". |
protobuf | string | The actual protobuf file contents. |
service_name | string 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
Field | Type | Description |
id | string | Unique connection id. |
name | string | A human-readable name for the connection. |
address | string | The remote address of the proxy service. |
ca_pem | string | The certificate authority of the proxy service. |
enabled | bool | Indicates this connection is enabled. |
connected | bool | Indicates this connection is currently in use. |
enable_http_proxy | bool | Indicates that this connection will handle HTTP proxying as well as GRPC. |
disable_volt_api | bool | Set to indicate the Volt API itself is not automatically exposed to the connection. |
challenge | string | Optional challenge that can be presented in the authentication request. |
target_id | string | The id of the target Volt that this connection is bound to. |
sync_did_registry | bool | Indicates that this connection hosts a DID registry that we should synchronise with. |
did_registry_sync_id | uint64 | The id of the last DID registry operation that was synchronised. |
sync_vc_registry | bool | Indicates that this connection hosts a DID registry that we should synchronise with. |
vc_registry_sync_timestamp | uint64 | The timestamp of the last VC registry operation that was synchronised. |
session_id | string | |
certificate | string |
Resource
The core Resource metadata schema.
Field | Type | Description |
id | string | The globally unique resource id. |
description | string | Optional description. |
name | string | Human-readable resource name. |
share_mode | ShareMode | Not in use. |
volt_id | string | The id of the Volt that hosts this resource. |
service_description | ServiceDescription | Optional description of any services exposed by this resource. |
attribute | ResourceAttribute repeated | Attributes assigned to the resource. |
platform_version | Version | The version of the platform. |
version | uint64 | The resource version. |
owner | string | The identity of the resource owner. |
created | uint64 | Creation timestamp, milliseconds since epoch. |
modified | uint64 | Last modification timestamp, milliseconds since epoch. |
status | ResourceStatus | Not in use. |
kind | string repeated | The taxonomy of the resource. |
online_status | OnlineStatus | 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`. |
size | uint64 | The size of the resource store in bytes. |
store | string | The path to the resource store. |
alias | string 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_hash | string | The hash of the resource content contained in the store. |
child | Resource repeated | Not yet supported. |
ResourceAttribute
A resource attribute enables storing arbitrary data associated with a resource.
Field | Type | Description |
id | uint32 | |
attribute_id | string | |
resource_id | string | |
data_type | AttributeDataType | |
value | AttributeValue repeated |
ServiceDescription
Describes a Volt service.
Field | Type | Description |
host_type | ServiceHostType | The configuration used by the host of this service. |
host_client_id | string | 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_id | string | 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_address | string | The address of the grpc server hosting this service. Only relevant to grpc-hosted services. |
host_ca_pem | string | The certificate authority (chain) that signed the service server certificate. This is only relevant to grpc-hosted services. |
host_public_key | string | 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_id | string | The connection id currently used to host this service. |
host_session_id | string | Internal use only. |
discoverable | DiscoveryMode | The discovery mode. |
ping_timestamp | int64 | The ping timestamp of the server hosting this service. |
proto_file | ProtoFile repeated | The protobuf definitions of the APIs exposed by this service. |
service_api | string repeated | The fully qualified names of the protobuf services, for example tdx.volt_api.webcam.v1.WebcamControlAPI. |
method | MethodDescription repeated | Internal use only. |
Session
Field | Type | Description |
id | string | |
identity_did | string | |
identity_name | string | |
ip | string | |
created | uint64 | |
modified | uint64 | |
expires | uint64 | |
credential | SessionCredential repeated | |
origin | string | |
status | SessionStatus |
SessionCredential
Field | Type | Description |
id | uint32 | The alias id. |
session_id | string | The corresponding session id. |
credential_type | string | The credential type, for example public key, verifiable credential, challenge etc. |
description | string | Optional description of this credential. |
vc_id | string | The id of the verifiable credential, if the credential type is volt:vc-claim. |
vc_json | string | The verifiable credential in JSON format, if the credential type is volt:vc-claim. |
vc_subject_id | string | The subject id extracted from the `vc_json` field. |
vc_issuer_id | string | The issuer id extracted from the `vc_json` field. |
vc_type | string | The comma-separated type(s) extracted from the `vc_json` field. |
challenge | string | The challenge string, if the credential type is volt:challenge. |
key_fingerprint | string | The key fingerprint, if the credential type is volt:public-key. |
public_key | string | The PEM-encoded public key, if the credential type is volt:public-key. |
private_key | string | 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. |
extra | string | Type-specific extra data stored with the credential. |
extra_2 | string | 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.
Field | Type | Description |
version_major | uint32 | |
version_minor | uint32 | |
version_patch | uint32 |
VoltEndpoint
Field | Type | Description |
id | string | The globally unique Volt id. |
display_name | string | Human-readable name of the Volt. |
local_address | string | The actual host/ip the volt is physically running on (might be a local ip if behind firewall). |
http_address | string | The address of the endpoint HTTP server. |
relay_address | string | 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_pem | string | The root certificate of the Relay instance referred to in `relay_address`. |
ca_pem | string | The self-signed certificate used by the volt to sign client certificates. |
public_key | string | The Volt public key in PEM format. |
fingerprint | string | The base58 fingerprint of the Volt public key. |
online_status | OnlineStatus | The online status of the Volt. |
has_relay | bool | Indicates that this Volt acts as a Relay. |
api_version | Version | The API version supported by the endpoint. |
description | string | Optional description of the endpoint. |
did_registry | string repeated | The list of DID registries that this Volt trusts. |
VoltParameters
Encapsulates the various Volt parameters that are configurable by the Volt owner.
Field | Type | Description |
id | string | |
name | string | The name of the Volt. |
description | string | Human-readable description of the Volt. |
db_driver | string | The database driver in use. |
location | string | The local file path location of the Volt storage. |
key_strategy | string | The key strategy in use, this determines how the root key is stored. |
key_id | string | The identifier for the key, the semantics depend on the key strategy in use. |
ca_pem | string | The Volt certificate authority. |
cert_pem | string | The Volt API server certificate. |
fixed_host | string | Optional hostname of the Volt if using DNS or a static IP address, e.g. tdxvolt.com |
grpc_port | int32 | Port to use for hosting the Volt management service. |
http_port | int32 | Port to use for hosting the Volt grpc service. |
http_key_path | string | The Volt http server key file path. |
http_cert_path | string | The Volt http server certificate file path. |
http_ca_path | string | The Volt http server certificate authority chain file path. |
discoverable | bool | Indicates the Volt will be discoverable by clients using the discovery api. |
authenticate_challenge | string | Optional challenge code that can be used aid in the process of authenticating clients. |
require_authenticate_challenge | bool | Indicates that clients must present the correct challenge code in order to be able to authenticate. |
confirm_stop | bool | Internal use only. |
auto_start | bool | Internal use only. |
enable_messaging | bool | Internal use only. |
has_relay | bool | 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_open | bool | Set to run the Relay open to any client, i.e. clients can utilise the Relay without first authenticating. |
enable_http_server | bool | Determines if the Volt HTTP server is enabled. |
http_server_secure | bool | Determines whether the HTTP server employs TLS. |
enable_http_forwarding | bool | Determines whether the HTTP server supports forwarding. |
enable_http_api | bool | Determines if the Volt REST API is exposed via the HTTP server. |
enable_websocket_api | bool | Determines if the Volt Websocket API is exposed via the HTTP server. |
address | string | The hostname:port at which the Volt API is currently running. |
encrypt_file_store | bool | Set to indicate the Volt file store is encrypted. |
connection_id | string | 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_pem | string | The certificate authority of the Relay if this is a remote connection via a Relay. |
http_address_override | string | 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`. |
alias | string | 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. |
version | Version | The runtime version this Volt is running. |
approve_on_challenge | bool | If set, indicates that any client that provides the correct challenge during authentication will automatically be approved to access the Volt. |
approve_on_did | bool | 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_registry | bool | If set, indicates that clients can register DIDs with this Volt. |
did_registry | string repeated | Zero or more URLs of trusted peer DID registries. |
enable_outbound_smtp | bool | If set, enables outbound SMTP. |
outbound_smtp_host | string | The SMTP host to use for sending emails. |
outbound_smtp_port | uint32 | The SMTP port to use for sending emails. |
outbound_smtp_user | string | The SMTP username to use for sending emails. |
outbound_smtp_password | string | The SMTP password to use for sending emails. |
enable_anonymous_create | bool | If set, enables sessions that authenticate using credentials rather than a DID to create resources in the 'anonymous' system folder. |
catch_all_auth_decision | PolicyDecision | The decision to apply to all authentication requests that do not match any other policy. The default is PROMPT. |
enable_policy_cache | bool | If set, enables caching of policy decisions. |
enable_terminal | bool | If set, enables the terminal API. |
start_time | uint64 | The time at which the Volt was started. |
AttributeDataType
Attribute data types.
Name | Number | Description |
ATTRIBUTE_DATA_TYPE_UNKNOWN | 0 | |
ATTRIBUTE_DATA_TYPE_STRING | 1 | |
ATTRIBUTE_DATA_TYPE_INTEGER | 2 | |
ATTRIBUTE_DATA_TYPE_REAL | 3 | |
ATTRIBUTE_DATA_TYPE_BOOLEAN | 4 | |
ATTRIBUTE_DATA_TYPE_BYTES | 5 | |
ATTRIBUTE_DATA_TYPE_IDENTITY | 100 | |
ATTRIBUTE_DATA_TYPE_RESOURCE | 101 |
DiscoveryMode
Name | Number | Description |
DISCOVERY_MODE_UNKNOWN | 0 | |
DISCOVERY_MODE_TRUSTED | 1 | Only local identities with explicit policy PERMIT can discover. |
DISCOVERY_MODE_PUBLIC | 2 | Any bound local identity can discover. |
DISCOVERY_MODE_TRUSTED_GLOBAL | 3 | Only identities with explicit policy PERMIT can discover, and the service will be available to local and non-local (Relayed) clients. |
DISCOVERY_MODE_PUBLIC_GLOBAL | 4 | Any bound identity can discover, and the service will be available to local and non-local (Relayed) clients. |
OnlineStatus
Name | Number | Description |
ONLINE_STATUS_UNKNOWN | 0 | |
ONLINE_STATUS_ONLINE | 1 | |
ONLINE_STATUS_OFFLINE | 2 |
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.
Name | Number | Description |
POLICY_DECISION_UNKNOWN | 0 | |
POLICY_DECISION_PROMPT | 1 | |
POLICY_DECISION_PERMIT | 2 | |
POLICY_DECISION_DENY | 3 | |
POLICY_DECISION_INDETERMINATE | 4 | |
POLICY_DECISION_NOT_APPLICABLE | 5 | |
POLICY_DECISION_APPLICABLE | 6 | |
POLICY_DECISION_PENDING | 7 |
ResourceStatus
Not used ATM.
Name | Number | Description |
RESOURCE_STATUS_UNKNOWN | 0 | |
RESOURCE_STATUS_LIVE | 1 | |
RESOURCE_STATUS_INACTIVE | 2 | |
RESOURCE_STATUS_DELETED | 999 |
SecureMode
Name | Number | Description |
SECURE_MODE_UNKNOWN | 0 | |
SECURE_MODE_INSECURE | 1 | |
SECURE_MODE_TLS | 2 |
ServiceHostType
Name | Number | Description |
SERVICE_HOST_TYPE_UNKNOWN | 0 | |
SERVICE_HOST_TYPE_BUILTIN | 1 | A built-in service hosted by the Volt. |
SERVICE_HOST_TYPE_SERVER | 2 | A service hosted by a grpc server other than the Volt. |
SERVICE_HOST_TYPE_RELAYED | 3 | 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
Name | Number | Description |
SESSION_STATUS_UNKNOWN | 0 | |
SESSION_STATUS_PENDING | 1 | |
SESSION_STATUS_LIVE | 2 | |
SESSION_STATUS_EXPIRED | 3 | |
SESSION_STATUS_REVOKED | 4 | |
SESSION_STATUS_REJECTED | 5 |
ShareMode
Not used ATM.
Name | Number | Description |
SHARE_MODE_UNKNOWN | 0 | |
SHARE_MODE_TRUSTED | 1 | |
SHARE_MODE_PUBLIC_READ | 2 |
Scalar Value Types
.proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
double | double | double | float | float64 | double | float | Float | |
float | float | float | float | float32 | float | float | Float | |
int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |