VoltAPI

Top

The top-level volt management service.

With the exception of `Authenticate`, all RPCs on this service must submit either a valid client certificate signed by the volt CA, or a signed JWT.

A client certificate can be obtained from the `Authenticate` method.

All methods include a `tdx.volt_api.volt.v1.Status` in the response. If the status contains a non-OK error code the client should assume the remainder of the message is invalid, unless otherwise indicated in the response documentation.

Authenticate()

Issues a request to authenticate on the volt.

All clients must successfully authenticate in order to gain any kind of access.

A client certificate is optional for this RPC, if omitted a JWT must be provided in the call metadata.

If the client plans to register one or more services with the Volt, it should use the 'host' field of the request so that the returned certificate has the appropriate SAN extension in place. Note that if the client IP address changes it will be necessary to re-authenticate the client and obtain a new certificate.

If the authenticate decision is 'permit', the response contains various details that should be persisted by the client, including the unique identifier assigned by the Volt and a signed client certificate along with the Volt CA certificate.

Request: AuthenticateRequest
Response: AuthenticateResponse

CanAccessResource()

Determine if an identity can perform a specific action on a resource.

Third party services can use this to interrogate the Volt policy and determine if a client has permission to perform a certain action on a resource.

Request: CanAccessResourceRequest
Response: CanAccessResourceResponse

CheckCompatibility()

Request: CheckCompatibilityRequest
Response: CheckCompatibilityResponse

Connect()

Creates a long-lived, bi-directional connection to the Volt.

The connection stream serves several purposes, including remote invocations via a Relay, Volt event notifications, pings and service registration management.

A connection stream is required in order for a client to be able to register services with the Volt.

When the stream is closed, any services registered on it will be set to offline.

Request: streaming ConnectRequest
Response: streaming ConnectResponse

CopyResource()

Copy a resource from one folder to another.

The resource metadata, attributes and store are copied.

The shares attributed to the resource are **not** currently copied.

n.b. Copy resources between Volts is not supported by this API. This is achieved by creating an API instance for the source and target Volts, getting the resource from the source and creating it on the target.

Request: CopyResourceRequest
Response: CopyResourceResponse

CreateVerifiableCredentialSession()

This is a work in progress - do not use.

Request: CreateVerifiableCredentialSessionRequest
Response: CreateVerifiableCredentialSessionResponse

DeleteAccess()

Remove a custom access rule, such as a file share.

Request: DeleteAccessRequest
Response: DeleteAccessResponse

DeleteResource()

Delete a resource from this volt.

Request: DeleteResourceRequest
Response: DeleteResourceResponse

DiscoverServices()

Discover services running on this volt.

Lookup is done via the exposed serviceAPI, e.g. tdx.volt_api.data.v1.SqliteServerAPI.

Request: DiscoverServicesRequest
Response: DiscoverServicesResponse

GetAccess()

Get access rule details.

Only rules in which the authenticated identity participates will be retrieved, in addition to any rules that target a resource that is owned by the authenticated identity.

If the authenticated identity is the Volt root, all rules will be retrieved that match the criteria.

Request: GetAccessRequest
Response: GetAccessResponse

GetIdentities()

Retrieve identities matching the given criteria.

Only identities that the authenticated identity has read access to will be retrieved.

Request: GetIdentitiesRequest
Response: GetIdentitiesResponse

GetIdentity()

Get details of a specific identity.

The identity will only be retrieved if the authenticated identity has read access to it.

Request: GetIdentityRequest
Response: GetIdentityResponse

GetIdentityToken()

NOT YET IMPLEMENTED.

Gets a credential for the currently authenticated client, signed by the volt CA.

Request: GetIdentityTokenRequest
Response: GetIdentityTokenResponse

GetParameters()

Retrieve the Volt parameters.

This is a privileged API call and requires Volt root access.

Request: GetParametersRequest
Response: GetParametersResponse

GetPolicy()

Retrieve the active Volt policy.

This is a privileged API call and requires Volt root access.

Request: GetPolicyRequest
Response: GetPolicyResponse

GetResource()

Get resource from this volt.

Request: GetResourceRequest
Response: GetResourceResponse

GetResources()

Get resources from this volt.

Request: GetResourcesRequest
Response: GetResourcesResponse

GetResourceAncestors()

Get ancestors of a resource.

Request: GetResourceAncestorsRequest
Response: GetResourceAncestorsResponse

GetResourceDescendants()

Get descendants of a resource.

Request: GetResourceDescendantsRequest
Response: GetResourceDescendantsResponse

GetSessions()

Get sessions.

Request: GetSessionsRequest
Response: GetSessionsResponse

Invoke()

Invoke a method.

This is primarily for use by Relay connections when proxying invocations.

Request: streaming InvokeRequest
Response: streaming InvokeResponse

MoveResource()

Move a resource from one folder to another.

Request: MoveResourceRequest
Response: MoveResourceResponse

RequestAccess()

Request access to a resource.

The subject of the access is assumed to be the identity of the currently authenticated peer.

Request: RequestAccessRequest
Response: RequestAccessResponse

SaveAccess()

Create or update an access rule.

Request: SaveAccessRequest
Response: SaveAccessResponse

SaveIdentity()

Create or update an identity.

Request: SaveIdentityRequest
Response: SaveIdentityResponse

SaveParameters()

Update Volt parameters.

This is a privileged call that requires Volt root access.

Request: SaveParametersRequest
Response: SaveParametersResponse

SaveResource()

Create or update resource in this volt.

Request: SaveResourceRequest
Response: SaveResourceResponse

SaveSession()

Save a session.

Request: SaveSessionRequest
Response: SaveSessionResponse

SetAccessRequestDecision()

Set Volt access request decision.

This is a privileged call that requires Volt root access.

Request: SetAccessRequestDecisionRequest
Response: SetAccessRequestDecisionResponse

SetPolicy()

Request: SetPolicyRequest
Response: SetPolicyResponse

SetServiceStatus()

Set the status of a Volt service.

Request: SetServiceStatusRequest
Response: SetServiceStatusResponse

Shutdown()

Used to shutdown remote Volts.

This is a privileged call that requires Volt root access.

Request: ShutdownRequest
Response: ShutdownResponse

SignVerify()

Sign or verify an arbitrary message using the Volt key.

Request: SignVerifyRequest
Response: SignVerifyResponse

AuthenticateRequest

Describes a request to authenticate on a Volt.

FieldTypeDescription
public_keystring

The client public key in PEM format. The Volt will create a session that is bound to this public key.

did_public_keystring

The client public key - must be in PEM format. If the client DID is lost or unknown for some reason, providing the public key here will allow the Volt to match it with the previously registered DID.

Note this is only valid when a DID has previously been registered using this public key.

didstring

An existing DID owned by the client.

The JWT presented with the authenticate call must be signed by the private key corresponding to this DID.

did_documentstring

If the client doesn't have an existing DID, a DID document can be provided here.

The document must include a proof that the client owns the public key given in `public_key`.

The Volt will register the DID on behalf of the client.

The JWT presented with the authenticate call must be signed by the private key corresponding to this document.

did_document_signaturestring

A base64-encoded signature of the DID document, only required if `did_document` is provided above.

client_namestring

A human-readable name of the entity requesting to authenticate.

challengestring

The volt challenge code, signed by the private key component of the `public_key` field above, and base64 encoded.

This is optional.

hoststring

The host name to add as a SAN to the issued certificate.

This is optional, if you don't intend to host services with the certificate this can be omitted.

verifiable_presentationVerifiablePresentation repeated

Optional verifiable credentials describing the client.

purge_aliasesbool

Reserved for internal use.

session_namestring

Optional additional name to differentiate between multiple sessions for a given client.

AuthenticateResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

session_idstring

identity_didstring

The identity id assigned to this authentication.

certstring

A certificate issued by the volt CA, binding the request public key to the identity.

Only valid for PERMIT authenticate decisions.

chainstring

The volt CA chain. This is used by the client in subsequent API calls to secure the connection.

decisionPolicyDecision

The authenticate decision.

request_timeint64

Reserved for internal use.

decision_timeint64

Reserved for internal use.

CanAccessResourceRequest

FieldTypeDescription
tokenstring

The subject of the access request.

This is optional, and if omitted will default to the authenticated account.

certstring

The subject of the access request.

This is optional, and if omitted will default to the authenticated account.

resource_idstring

The resource in question.

accessstring

The type of access that is required.

CanAccessResourceResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

identity_didstring

The identity subject that the access relates to.

issuer_idstring

Optional identity that issued the access.

resource_idstring

The resource the access relates to.

accessstring

The access type.

decisionPolicyDecision

The policy decision for this access request.

CheckCompatibilityRequest

FieldTypeDescription
versionVersion

The client platform API version.

CheckCompatibilityResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

versionVersion

The target Volt API version.

ConnectAcknowledge

FieldTypeDescription
connection_idstring

A unique identifier for this connection.

timestampuint64

The current time on the Volt.

ping_intervaluint32

The interval at which the target will send ping requests to the client.

ConnectAuthRequest

FieldTypeDescription
sessionSession

contextstring

challengestring

timestampuint64

ConnectDIDRegistryUpdate

FieldTypeDescription
updateDIDRegistryUpdate

ConnectEvent

FieldTypeDescription
connect_auth_requestConnectAuthRequest

An authentication request event.

connect_resourceConnectResource

A resource event notification, such as updated or deleted.

did_registry_updateConnectDIDRegistryUpdate

A DID registry entry update.

ConnectGoodbye

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

endedbool

Set if the connection was ended gracefully, as opposed to errored.

ConnectHello

All fields in this message are optional, send an empty message if necessary.

FieldTypeDescription
addressstring

Optionally specify the calling address of the peer.

Not currently in use.

online_servicesbool

Set to automatically make **all** services owned by the calling identity online.

subscribe_resource_eventsbool

Set to receive notification of resource events.

relay_idstring

Set this if you are connecting to a relay, i.e. the Volt you are sending this message to is a relay.

This indicates that you are happy to receive method invocations from clients of the Relay.

This will usually be set to the `id` of your Volt, but in theory any client could receive remote invocation requests in this way.

relay_namestring

A friendly name to present to Relay clients.

relay_descriptionstring

relay_ca_pemstring

The certificate authority to present to Relay clients.

relay_discoverablebool

Set to indicate the connection is discoverable to other Relay clients.

subscribe_auth_requestsbool

Set to receive notification of authentication requests.

accept_invocationbool

Set to indicate the connection will accept method invocation requests.

subscribe_did_registry_updatesbool

Set to subscribe to DID registry updates from the peer.

ping_intervaluint32

The interval at which the client will send ping requests to the target.

timestampuint64

The current time on the client.

ConnectMessage

This message is reserved for internal use.

FieldTypeDescription
idstring

thread_idstring

to_idstring

to_identity_idstring

to_namestring

messagestring

timestampuint64

from_idstring

from_identity_idstring

from_namestring

receiptstring repeated

message_typeConnectMessageType

message_relayConnectMessageRelay

ConnectPing

A connection ping message - intentionally empty.

ConnectRelay

FieldTypeDescription
connectedbool

Indicates the Relay connection status.

ConnectRequest

One of the following payloads will be present in a given ConnectRequest message.

FieldTypeDescription
helloConnectHello

A ConnectHello message is the first message a client sends to the target upon successfully starting the call.

goodbyeConnectGoodbye

Indicates the client is closing the connection.

msgConnectMessage

Reserved for internal use.

pingConnectPing

Clients should periodically send ping requests to the target to confirm the stream is still live.

invoke_responseInvokeResponse

Send invocation responses back to the caller.

n.b. The 'request' and 'response' semantics are inverted with remote invocations because the Relayed connection is established by a request **from** the 'target' Volt to the Relay. Hence any invocation on behalf of a client of the Relay involves sending a **response** back down the Relay connection to the 'target' Volt.

http_responseHttpResponse

Send HTTP response back to the originating request.

n.b. The 'request' and 'response' semantics are inverted with HTTP proxying for the same reason as `invoke_response` above.

ConnectResource

FieldTypeDescription
eventConnectResourceEvent

The type of resource event that has occurred.

resourceResource

Details of the resource.

ConnectResponse

One of the following payloads will be present in a given ConnectResponse message.

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

acknowledgeConnectAcknowledge

Server response to initial handshake.

goodbyeConnectGoodbye

Indicates the server is ending the connection.

evtConnectEvent

Notifies clients of various events on the Volt.

msgConnectMessage

Reserved for internal use.

pingConnectPing

Periodic ping response.

invoke_requestInvokeRequest

Send an invocation request to a remote target.

n.b. The 'request' and 'response' semantics are inverted for remote invocations because the Relayed connection is established by a request **from** the 'target' Volt to the Relay. Hence any invocation on behalf of a client of the Relay involves sending a **response** back down the Relay connection to the 'target' Volt.

http_requestHttpRequest

Send an HTTP request to a remote target.

n.b. The 'request' and 'response' semantics are inverted for HTTP requests for the same reason as `invoke_request` above.

CopyResourceRequest

FieldTypeDescription
resource_idstring

The id of the resource to copy.

to_resource_idstring

The id of the resource to receive the new copy.

modeCopyResourceMode

The copy mode to use.

recursivebool

Indicates if all descendants of the resource should be copied too. Only relevant for COPY_RESOURCE_MODE_COPY mode.

from_resource_idstring

The parent resource to link from, only relevant for COPY_RESOURCE_MODE_LINK mode.

CopyResourceResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

CreateVerifiableCredentialSessionRequest

FieldTypeDescription
presentationstring

CreateVerifiableCredentialSessionResponse

FieldTypeDescription
statusStatus

session_idstring

DeleteAccessRequest

FieldTypeDescription
idstring

The id of the access rule to delete.

DeleteAccessResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

DeleteResourceRequest

FieldTypeDescription
resource_idstring

The resource to delete.

recursivebool

Set to indicate all descendant resources should also be deleted.

If this is not set and the resource has descendants, the call will fail.

parent_idstring

Set to attempt to unlink the resource from this parent resource, rather than completely delete it.

The resource will be removed as a descendant from the `parent_id` resource. If the resource is has more than one parent, it will not be removed from those other parents.

Note that if the resource's only parent is `parent_id` it will be removed from that parent and deleted as normal.

DeleteResourceResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

DiscoverServicesRequest

FieldTypeDescription
service_apistring repeated

List the service APIs that should be discovered.

The response will include services that match **any of** the terms given.

Use of '*' to indicate wildcards is supported.

include_offlinebool

Set to indicate that offline services should be included in the response.

include_protobufbool

Set to include the service protobuf in the response.

DiscoverServicesResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

resourceResource repeated

The services that were discovered.

GetAccessRequest

FieldTypeDescription
resource_idstring

The resource id that is the target of the access rule. If omitted, all resources will be considered.

identity_didstring

The identity id that is the subject of the access rule. If omitted, all identities will be considered.

issuer_idstring

The issuer of the access rule. If omitted, all issuers will be considered.

accessstring

The type of access to retrieve, if omitted all access will be considered.

decisionPolicyDecision

The type of decision, if omitted all decisions will be considered.

GetAccessResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

accessAccess repeated

The access rules that match the criteria.

GetIdentitiesRequest

FieldTypeDescription
namestring

Optional name of the identity.

Use '*' to perform a wildcard search.

If omitted all identities will be retrieved.

aliasIdentityAlias

The identity alias criteria, if omitted all identities will be considered.

GetIdentitiesResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

identityIdentity repeated

The identity list that matched the criteria.

GetIdentityRequest

One of `identity_did` or `fingerprint` must be populated.

FieldTypeDescription
identity_didstring

The id of the identity to retrieve.

fingerprintstring

The public key fingerprint of the identity to retrieve.

GetIdentityResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

identityIdentity

The identity details.

GetIdentityTokenRequest

FieldTypeDescription
ttlint32

The token TTL, in seconds.

audiencestring

The intended token audience - usually the common name of the target volt

CA.

GetIdentityTokenResponse

FieldTypeDescription
statusStatus

tokenstring

GetParametersRequest

This an empty message.

GetParametersResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

parametersVoltParameters

The retrieved Volt parameters.

GetPolicyRequest

This an empty message.

FieldTypeDescription
custom_policybool

Set to only retrieve the custom policy document.

GetPolicyResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

policystring

The live policy in JSON format.

GetResourceAncestorsRequest

FieldTypeDescription
resource_idstring

The resource id whose ancestors will be retrieved.

include_resource_idbool

Optional - if set the resource_id resource will be included in the set of resources returned.

depthint32

Optional - restrict the depth search, e.g. for immediate parents depth = 1

ancestor_kindstring

Optional - only match ancestors of the given kind.

ancestor_idstring

Optional - can be used to determine if a resource is an ancestor.

GetResourceAncestorsResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

ancestorResource repeated

The retrieved ancestors.

GetResourceDescendantsRequest

FieldTypeDescription
resource_idstring

The resource id whose descendants will be retrieved.

include_resource_idbool

Optional - if set, the fully populated `resource_id` resource (i.e. the parent) will be included in the set of resources returned.

depthint32

Optional - restrict the depth search, e.g. for immediate children depth = 1

descendant_kindstring repeated

Optional - only match descendants of the given kind.

If multiple kinds are given, resources matching **any of** the kinds will be included.

descendant_idstring

Optional - can be used to determine if a resource is a descendant.

parent_idstring

Optional - restrict to descendants of a given parent, for use in multi-parent hierarchies.

namestring

Restrict to a specific named resource.

GetResourceDescendantsResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

descendantResource repeated

The retrieved descendants.

GetResourceRequest

FieldTypeDescription
resource_idstring

The id of the resource to retrieve.

include_protobufbool

Set to include service description protobuf in the response, if applicable.

GetResourceResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

resourceResource

The retrieved resource metadata.

GetResourcesRequest

By default, the lookup is performed by combining the criteria below in the form:

(id = id[0] or id = id[1]) and (name = name[0] or name = name[1]) etc...

To combine using 'or' rather than 'and', set the `combine_terms_exclusive` flag.

Also see note below regarding attributes.

FieldTypeDescription
idstring repeated

namestring repeated

Wildcards permitted.

descriptionstring repeated

Wildcards permitted.

kindstring repeated

Wildcards permitted.

parent_idstring repeated

service_apistring repeated

Wildcards permitted.

ownerstring repeated

storestring repeated

combine_terms_exclusivebool

Indicates that the above terms should be combined using 'or' rather than 'and' (the default).

attributeResourceAttributeQuery repeated

Attributes to search by.

any_ofbool

If set, will return resources where *any of* the attribute queries apply, otherwise will only return resources where *all of* the attribute queries apply.

include_protobufbool

Set to include service description protobuf in the response where applicable.

modified_sinceuint64

Only retrieve resources that have been modified after the given timestamp. Default is 0, which means all resources will be returned.

limituint32

Limit the number of resources returned. Default is 0, which means all resources will be returned.

GetResourcesResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

resourceResource repeated

The list of resources that match the lookup.

GetSessionsRequest

FieldTypeDescription
idstring

identity_didstring

identity_namestring

statusSessionStatus

GetSessionsResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

sessionSession repeated

InvokeRequest

FieldTypeDescription
invoke_iduint64

Client-assigned identifier for the request. Will be used to match responses and any subsequent requests.

tokenstring

The client token to use for the invocation.

This contains the key and iv used to encrypt the payload, which only the token audience can access because the key and iv are themselves encrypted using the public key of the invocation target.

target_didstring repeated

The DID of the target at each hop of the path to the service.

This is used by Relays to route the request.

payloadbytes

A serialised and encrypted instance of `RemoteResponse` in pure binary format.

json_payloadstring

A serialised and encrypted instance of `RemoteResponse` as serialised JSON.

client_endbool

Indicates the client has ended the invocation.

hop_indexuint32

Reserved for internal use.

target_service_idstring

Reserved for internal use.

InvokeResponse

FieldTypeDescription
invoke_iduint64

The invocation id to match the originating request.

payloadbytes

A serialised and encrypted instance of `RemoteRequest` in pure binary format.

json_payloadstring

A serialised and encrypted instance of `RemoteRequest` as serialised JSON.

statusStatus

Details of any error that occurred on the call.

server_endbool

Indicates the server has ended the invocation.

MoveResourceRequest

FieldTypeDescription
resource_idstring

The id of the resource to move.

from_resource_idstring

The resource the parent folder to move the resource from.

to_resource_idstring

The target folder to move the resource into.

MoveResourceResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

RequestAccessRequest

FieldTypeDescription
resource_idstring

The target resource id.

accessstring

The type of access requested.

RequestAccessResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

resource_idstring

The resource being accessed.

identity_didstring

The identity attempting access.

issuer_idstring

The identity of the issuer of the access.

accessstring

Requested access.

decisionPolicyDecision

Assigned decision.

request_timeint64

Time at which the request was made.

decision_timeint64

Time at which the decision was taken.

request_countint32

Counter of number times this access was requested.

ResourceAttributeQuery

FieldTypeDescription
attribute_idstring

data_typeAttributeDataType

valueAttributeValue

SaveAccessRequest

FieldTypeDescription
accessAccess

Omit `id` if creating new access.

SaveAccessResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

SaveIdentityRequest

FieldTypeDescription
identityIdentity

Details of the identity to save.

createbool

Set to indicate this is a new identity.

delete_aliasIdentityAlias repeated

The list of aliases that should be removed.

For example, this allows a simple form of key rotation whereby an existing public key alias is replaced by a new one while still maintaining the same root identity id.

create_in_parent_idstring

Reserved for system use.

purge_aliasesbool

Set to indicate the identity aliases should be purged before saving the identity.

If the `identity` field contains aliases they will be saved after the purge.

If the `identity` field does not contain aliases this effectively deletes all aliases for this identity.

This allows you to selectively update aliases if required, i.e. don't set this flag and include a single alias in the update.

did_documentstring

did_update_signaturestring

The signature of the identity did document, if present.

SaveIdentityResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

identityIdentity

The updated identity details.

SaveParametersRequest

FieldTypeDescription
parametersVoltParameters

The updated parameters.

key_passphrasestring

The current root key passphrase. Only necessary if changes are being made to the Volt key.

new_key_passphrasestring

The new root key passphrase. Only necessary if changes are being made to the Volt key.

SaveParametersResponse

FieldTypeDescription
statusStatus

Details of any errors that occurred on the call.

parametersVoltParameters

The updated Volt parameters.

reconnectbool

If set, the client will need to reconnect (usually because the key has changed).

SaveResourceRequest

FieldTypeDescription
resourceResource

Details of the resource to save.

createbool

Set to indicate this is a new resource.

create_in_parent_idstring

The id of the folder resource in which a new resource should be created.

If omitted, the home folder of the currently authenticated identity will be used.

purge_attributesbool

Set to indicate the resource attributes should be purged before saving the resource.

If the `resource` field contains attributes they will be saved after the purge.

If the `resource` field does not contain attributes this effectively deletes all attributes for this resource.

This allows you to selectively update attributes if required, i.e. don't set this flag and include a single attribute in the update.

SaveResourceResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

resourceResource

The updated resource.

SaveSessionRequest

FieldTypeDescription
sessionSession

SaveSessionResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

sessionSession

SetAccessRequestDecisionRequest

FieldTypeDescription
idstring

The id of the access request.

decisionPolicyDecision

The decision to save against the access request.

SetAccessRequestDecisionResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

SetPolicyRequest

FieldTypeDescription
custom_policystring

SetPolicyResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

SetServiceStatusRequest

FieldTypeDescription
serviceResource

The service description details.

SetServiceStatusResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

resourceResource

The updated service resource details.

ShutdownRequest

This message is emtpy.

ShutdownResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

SignVerifyRequest

FieldTypeDescription
verifybool

Set to indicate this is a request to verify rather than sign.

encodebool

Set to indicate the signature should be base64 encoded in the response.

Only valid when signing.

messagestring

The message to sign.

Only valid when signing.

digest_rawbytes

The digest in raw binary form.

Only valid if verifying.

digest_encodedstring

The digest encoded using base64.

Only valid if verifying.

SignVerifyResponse

Note that if verification was successful the response will be empty (there is no error and no digest is returned).

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

digestbytes

The signature in raw binary form.

digest_encodedstring

The signature encoded using base64.

ConnectMessageRelay

Reserved for internal use.

NameNumberDescription
CONNECT_MESSAGE_RELAY_UNKNOWN0

CONNECT_MESSAGE_RELAY_OUTGOING1

CONNECT_MESSAGE_RELAY_INCOMING2

ConnectMessageType

Reserved for internal use.

NameNumberDescription
CONNECT_MESSAGE_TYPE_UNKNOWN0

CONNECT_MESSAGE_TYPE_ORIGINAL1

CONNECT_MESSAGE_TYPE_ECHO2

CONNECT_MESSAGE_TYPE_FORWARD3

ConnectResourceEvent

NameNumberDescription
CONNECT_RESOURCE_EVENT_UNKNOWN0

CONNECT_RESOURCE_EVENT_CREATE1

CONNECT_RESOURCE_EVENT_UPDATE2

CONNECT_RESOURCE_EVENT_DELETE3

CONNECT_RESOURCE_EVENT_CREATE_CHILD4

CONNECT_RESOURCE_EVENT_DELETE_CHILD5

CONNECT_RESOURCE_EVENT_DATABASE_WRITE6

CopyResourceMode

NameNumberDescription
COPY_RESOURCE_MODE_UNKNOWN0

COPY_RESOURCE_MODE_COPY1

COPY_RESOURCE_MODE_LINK2

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.

issuer_idstring

issuer_namestring

issuer_kindstring repeated

accessstring

Requested access.

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

Set to indicate that this Volt acts as a Relay.

api_versionVersion

descriptionstring

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.

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.

IdentityType

NameNumberDescription
IDENTITY_TYPE_UNKNOWN0

IDENTITY_TYPE_USER1

IDENTITY_TYPE_AUTHORITY2

IDENTITY_TYPE_GROUP3

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

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

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)