Protocol Documentation¶

This page documents the Protobuf Services and Messages which compose the Trinsic API.

sdk/options/v1/options.proto¶

TrinsicOptions¶

Configuration for Trinsic SDK Services

Field	Type	Description
server_endpoint	string	Trinsic API endpoint. Defaults to `prod.trinsic.cloud`
server_port	int32	Trinsic API port; defaults to `443`
server_use_tls	bool	Whether TLS is enabled between SDK and Trinsic API; defaults to `true`
auth_token	string	Authentication token for SDK calls; defaults to empty string (unauthenticated)

Default ecosystem ID to use for various SDK calls; defaults to default string default_ecosystem = 5; |

Top

services/google/api/annotations.proto¶

File-level Extensions¶

Extension	Type	Base	Number	Description
http	HttpRule	.google.protobuf.MethodOptions	72295728	See `HttpRule`.

Top

services/google/api/http.proto¶

CustomHttpPattern¶

A custom pattern is used for defining custom HTTP verb.

Field	Type	Description
kind	string	The name of this custom HTTP verb.
path	string	The path matched by this custom verb.

Http¶

Defines the HTTP configuration for an API service. It contains a list of [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method to one or more HTTP REST API methods.

Field	Type	Description
rules	HttpRule[]	A list of HTTP configuration rules that apply to individual API methods.

NOTE: All service configuration rules follow "last one wins" order. | | fully_decode_reserved_expansion | bool | When set to true, URL path parameters will be fully URI-decoded except in cases of single segment matches in reserved expansion, where "%2F" will be left encoded.

The default behavior is to not decode RFC 6570 reserved characters in multi segment matches. |

HttpRule¶

gRPC Transcoding¶

gRPC Transcoding is a feature for mapping between a gRPC method and one or more HTTP REST endpoints. It allows developers to build a single API service that supports both gRPC APIs and REST APIs. Many systems, including Google APIs, Cloud Endpoints, gRPC Gateway, and Envoy proxy support this feature and use it for large scale production services.

HttpRule defines the schema of the gRPC/REST mapping. The mapping specifies how different portions of the gRPC request message are mapped to the URL path, URL query parameters, and HTTP request body. It also controls how the gRPC response message is mapped to the HTTP response body. HttpRule is typically specified as an google.api.http annotation on the gRPC method.

Each mapping specifies a URL path template and an HTTP method. The path template may refer to one or more fields in the gRPC request message, as long as each field is a non-repeated field with a primitive (non-message) type. The path template controls how fields of the request message are mapped to the URL path.

Example:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http) = {
        get: "/v1/{name=messages/*}"
    };
  }
}
message GetMessageRequest {
  string name = 1; // Mapped to URL path.
}
message Message {
  string text = 1; // The resource content.
}

This enables an HTTP REST to gRPC mapping as below:

HTTP	gRPC
`GET /v1/messages/123456`	`GetMessage(name: "messages/123456")`

Any fields in the request message which are not bound by the path template automatically become HTTP query parameters if there is no HTTP request body. For example:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http) = {
        get:"/v1/messages/{message_id}"
    };
  }
}
message GetMessageRequest {
  message SubMessage {
    string subfield = 1;
  }
  string message_id = 1; // Mapped to URL path.
  int64 revision = 2;    // Mapped to URL query parameter `revision`.
  SubMessage sub = 3;    // Mapped to URL query parameter `sub.subfield`.
}

This enables a HTTP JSON to RPC mapping as below:

HTTP	gRPC
`GET /v1/messages/123456?revision=2&sub.subfield=foo`
`GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:
"foo"))`

Note that fields which are mapped to URL query parameters must have a primitive type or a repeated primitive type or a non-repeated message type. In the case of a repeated type, the parameter can be repeated in the URL as ...?param=A&param=B. In the case of a message type, each field of the message is mapped to a separate parameter, such as ...?foo.a=A&foo.b=B&foo.c=C.

For HTTP methods that allow a request body, the body field specifies the mapping. Consider a REST update method on the message resource collection:

service Messaging {
  rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
    option (google.api.http) = {
      patch: "/v1/messages/{message_id}"
      body: "message"
    };
  }
}
message UpdateMessageRequest {
  string message_id = 1; // mapped to the URL
  Message message = 2;   // mapped to the body
}

The following HTTP JSON to RPC mapping is enabled, where the representation of the JSON in the request body is determined by protos JSON encoding:

HTTP	gRPC
`PATCH /v1/messages/123456 { "text": "Hi!" }`	`UpdateMessage(message_id:
"123456" message { text: "Hi!" })`

The special name * can be used in the body mapping to define that every field not bound by the path template should be mapped to the request body. This enables the following alternative definition of the update method:

service Messaging {
  rpc UpdateMessage(Message) returns (Message) {
    option (google.api.http) = {
      patch: "/v1/messages/{message_id}"
      body: "*"
    };
  }
}
message Message {
  string message_id = 1;
  string text = 2;
}

The following HTTP JSON to RPC mapping is enabled:

HTTP	gRPC
`PATCH /v1/messages/123456 { "text": "Hi!" }`	`UpdateMessage(message_id:
"123456" text: "Hi!")`

Note that when using * in the body mapping, it is not possible to have HTTP parameters, as all fields not bound by the path end in the body. This makes this option more rarely used in practice when defining REST APIs. The common usage of * is in custom methods which don't use the URL at all for transferring data.

It is possible to define multiple HTTP methods for one RPC by using the additional_bindings option. Example:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http) = {
      get: "/v1/messages/{message_id}"
      additional_bindings {
        get: "/v1/users/{user_id}/messages/{message_id}"
      }
    };
  }
}
message GetMessageRequest {
  string message_id = 1;
  string user_id = 2;
}

This enables the following two alternative HTTP JSON to RPC mappings:

HTTP	gRPC
`GET /v1/messages/123456`	`GetMessage(message_id: "123456")`
`GET /v1/users/me/messages/123456`	`GetMessage(user_id: "me" message_id:
"123456")`

Rules for HTTP mapping¶

Leaf request fields (recursive expansion nested messages in the request message) are classified into three categories:
Fields referred by the path template. They are passed via the URL path.
Fields referred by the [HttpRule.body][google.api.HttpRule.body]. They are passed via the HTTP request body.
All other fields are passed via the URL query parameters, and the parameter name is the field path in the request message. A repeated field can be represented as multiple query parameters under the same name.
If [HttpRule.body][google.api.HttpRule.body] is "*", there is no URL query parameter, all fields are passed via URL path and HTTP request body.
If [HttpRule.body][google.api.HttpRule.body] is omitted, there is no HTTP request body, all fields are passed via URL path and URL query parameters.

Path template syntax¶

Template = "/" Segments [ Verb ] ;
Segments = Segment { "/" Segment } ;
Segment  = "*" | "**" | LITERAL | Variable ;
Variable = "{" FieldPath [ "=" Segments ] "}" ;
FieldPath = IDENT { "." IDENT } ;
Verb     = ":" LITERAL ;

The syntax * matches a single URL path segment. The syntax ** matches zero or more URL path segments, which must be the last part of the URL path except the Verb.

The syntax Variable matches part of the URL path as specified by its template. A variable template must not contain other variables. If a variable matches a single path segment, its template may be omitted, e.g. {var} is equivalent to {var=*}.

The syntax LITERAL matches literal text in the URL path. If the LITERAL contains any reserved character, such characters should be percent-encoded before the matching.

If a variable contains exactly one path segment, such as "{var}" or "{var=*}", when such a variable is expanded into a URL path on the client side, all characters except [-_.~0-9a-zA-Z] are percent-encoded. The server side does the reverse decoding. Such variables show up in the Discovery Document as {var}.

If a variable contains multiple path segments, such as "{var=foo/*}" or "{var=**}", when such a variable is expanded into a URL path on the client side, all characters except [-_.~/0-9a-zA-Z] are percent-encoded. The server side does the reverse decoding, except "%2F" and "%2f" are left unchanged. Such variables show up in the Discovery Document as {+var}.

Using gRPC API Service Configuration¶

gRPC API Service Configuration (service config) is a configuration language for configuring a gRPC service to become a user-facing product. The service config is simply the YAML representation of the google.api.Service proto message.

As an alternative to annotating your proto file, you can configure gRPC transcoding in your service config YAML files. You do this by specifying a HttpRule that maps the gRPC method to a REST endpoint, achieving the same effect as the proto annotation. This can be particularly useful if you have a proto that is reused in multiple services. Note that any transcoding specified in the service config will override any matching transcoding configuration in the proto.

Example:

http:
  rules:
    # Selects a gRPC method and applies HttpRule to it.
    - selector: example.v1.Messaging.GetMessage
      get: /v1/messages/{message_id}/{sub.subfield}

Special notes¶

When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the proto to JSON conversion must follow the proto3 specification.

While the single segment variable follows the semantics of RFC 6570 Section 3.2.2 Simple String Expansion, the multi segment variable does not follow RFC 6570 Section 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion does not expand special characters like ? and #, which would lead to invalid URLs. As the result, gRPC Transcoding uses a custom encoding for multi segment variables.

The path variables must not refer to any repeated or mapped field, because client libraries are not capable of handling such variable expansion.

The path variables must not capture the leading "/" character. The reason is that the most common use case "{var}" does not capture the leading "/" character. For consistency, all path variables must share the same behavior.

Repeated message fields must not be mapped to URL query parameters, because no client library can support such complicated mapping.

If an API needs to use a JSON array for request or response body, it can map the request or response body to a repeated field. However, some gRPC Transcoding implementations may not support this feature.

Field	Type	Description
selector	string	Selects a method to which this rule applies.

Refer to [selector][google.api.DocumentationRule.selector] for syntax details. | | get | string | Maps to HTTP GET. Used for listing and getting information about resources. | | put | string | Maps to HTTP PUT. Used for replacing a resource. | | post | string | Maps to HTTP POST. Used for creating a resource or performing an action. | | delete | string | Maps to HTTP DELETE. Used for deleting a resource. | | patch | string | Maps to HTTP PATCH. Used for updating a resource. | | custom | CustomHttpPattern | The custom pattern is used for specifying an HTTP method that is not included in the pattern field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule. The wild-card rule is useful for services that provide content to Web (HTML) clients. | | body | string | The name of the request field whose value is mapped to the HTTP request body, or * for mapping all request fields not captured by the path pattern to the HTTP body, or omitted for not having any HTTP request body.

NOTE: the referred field must be present at the top-level of the request message type. | | response_body | string | Optional. The name of the response field whose value is mapped to the HTTP response body. When omitted, the entire response message will be used as the HTTP response body.

NOTE: The referred field must be present at the top-level of the response message type. | | additional_bindings | HttpRule[] | Additional HTTP bindings for the selector. Nested bindings must not contain an additional_bindings field themselves (that is, the nesting may only be one level deep). |

Top

services/options/field-options.proto¶

AnnotationOption¶

Field	Type	Description
active	bool	Is this annotation active
message	string	Custom annotation message to provide

SdkTemplateOption¶

Field	Type	Description
anonymous	bool	Whether the service endpoint allows anonymous (no auth token necessary) authentication This is used by the `protoc-gen-trinsic-sdk` plugin for metadata.
ignore	bool	Whether the SDK template generator should ignore this method. This method will be wrapped manually.
no_arguments	bool	Whether the SDK template generator should generate this method without arguments, eg ProviderService.GetEcosystemInfo() where the request object is empty
experimental	AnnotationOption	This endpoint is experimental. Consider it in beta, so documentation may be incomplete or incorrect.
deprecated	AnnotationOption	This endpoint is deprecated. It will be removed in the future.

File-level Extensions¶

Extension	Type	Base	Number	Description
optional	bool	.google.protobuf.FieldOptions	60000	Whether field is optional in Trinsic's backend. This is not the same as an `optional` protobuf label; it only impacts documentation generation for the field.
sdk_template_option	SdkTemplateOption	.google.protobuf.MethodOptions	60001

Top

services/verifiable-credentials/templates/v1/templates.proto¶

Service - CredentialTemplates¶

Method Name	Request Type	Response Type	Description
Create	CreateCredentialTemplateRequest	CreateCredentialTemplateResponse	Create a credential template in the current ecosystem
Get	GetCredentialTemplateRequest	GetCredentialTemplateResponse	Fetch a credential template by ID
Update	UpdateCredentialTemplateRequest	UpdateCredentialTemplateResponse	Update metadata of a template
List	ListCredentialTemplatesRequest	ListCredentialTemplatesResponse	Search credential templates using SQL, returning strongly-typed template data
Search	SearchCredentialTemplatesRequest	SearchCredentialTemplatesResponse	Search credential templates using SQL, returning raw JSON data
Delete	DeleteCredentialTemplateRequest	DeleteCredentialTemplateResponse	Delete a credential template from the current ecosystem by ID
CreateVerificationTemplate	CreateVerificationTemplateRequest	CreateVerificationTemplateResponse	Create/update verification templates
ListVerificationTemplates	ListVerificationTemplatesRequest	ListVerificationTemplatesResponse
GetVerificationTemplate	GetVerificationTemplateRequest	GetVerificationTemplateResponse
UpdateVerificationTemplate	UpdateVerificationTemplateRequest	UpdateVerificationTemplateResponse
DeleteVerificationTemplate	DeleteVerificationTemplateRequest	DeleteVerificationTemplateResponse

AppleWalletOptions¶

Configuration options for Apple Wallet when

Field	Type	Description
background_color	string	Background color, in hex format, of credential when stored in an Apple Wallet.
foreground_color	string	Foreground color, in hex format, of credential when stored in an Apple Wallet.
label_color	string	Label color, in hex format, of credential when stored in an Apple Wallet.
primary_field	string	The ID of the template field which should be used as the primary field of a credential.
secondary_fields	string[]	The secondary fields of the credential. This is a mapping between the order of a secondary field (0 or 1) and the field name.
auxiliary_fields	string[]	The auxiliary fields of the credential. This is a mapping between the order of an auxiliary field (0 or 1) and the field name.

CreateCredentialTemplateRequest¶

Request to create a new template

Field	Type	Description
name	string	Name of new template. Must be a unique identifier within its ecosystem.
fields	CreateCredentialTemplateRequest.FieldsEntry[]	Fields which compose the template
allow_additional_fields	bool	Whether credentials may be issued against this template which have fields not specified in `fields`
title	string	Human-readable name of template
description	string	Human-readable description of template
field_ordering	CreateCredentialTemplateRequest.FieldOrderingEntry[]	Optional map describing how to order and categorize the fields within the template. The key of this map is the field `name`. If not provided, this will be auto-generated.
apple_wallet_options	AppleWalletOptions	Options for rendering the template in Apple Wallet

CreateCredentialTemplateRequest.FieldOrderingEntry¶

Field	Type	Description
key	string
value	FieldOrdering

CreateCredentialTemplateRequest.FieldsEntry¶

Field	Type	Description
key	string
value	TemplateField

CreateCredentialTemplateResponse¶

Response to CreateCredentialTemplateRequest

Field	Type	Description
data	TemplateData	Created template

CreateVerificationTemplateRequest¶

Field	Type	Description
name	string	Name of new template. Must be a unique identifier within its ecosystem.
fields	CreateVerificationTemplateRequest.FieldsEntry[]	Fields which will be required in the verification proof template

CreateVerificationTemplateRequest.FieldsEntry¶

Field	Type	Description
key	string
value	VerificationTemplateField

CreateVerificationTemplateResponse¶

Field	Type	Description
data	VerificationTemplateData

DeleteCredentialTemplateRequest¶

Request to delete a template by ID

Field	Type	Description
id	string	ID of template to delete

DeleteCredentialTemplateResponse¶

Response to DeleteCredentialTemplateRequest

DeleteVerificationTemplateRequest¶

Field	Type	Description
verification_template_id	string

DeleteVerificationTemplateResponse¶

This space intentionally left blank

FieldOrdering¶

Ordering information for a template field

Field	Type	Description
order	int32	The order of the field; must be unique within the Template. Fields are sorted by order ascending when displaying a credential. Field orders must be contiguous from `0` to the number of fields minus 1.
section	string	The human-readable name of the section this field appears in; used to group together fields when displaying a credential. Sections must be contiguous with respect to `order`.

GetCredentialTemplateRequest¶

Request to fetch a template by ID

Field	Type	Description
id	string	ID of template to fetch

GetCredentialTemplateResponse¶

Response to GetCredentialTemplateRequest

Field	Type	Description
template	TemplateData	Template fetched by ID

GetVerificationTemplateRequest¶

Request to fetch a template by ID

Field	Type	Description
id	string	ID of template to fetch

GetVerificationTemplateResponse¶

Response to GetCredentialTemplateRequest

Field	Type	Description
template	VerificationTemplateData	Template fetched by ID

ListCredentialTemplatesRequest¶

Request to list templates using a SQL query

Field	Type	Description
query	string	SQL query to execute. Example: `SELECT * FROM c WHERE c.name = 'Diploma'`
continuation_token	string	Token provided by previous `ListCredentialTemplatesResponse` if more data is available for query

ListCredentialTemplatesResponse¶

Response to ListCredentialTemplatesRequest

Field	Type	Description
templates	TemplateData[]	Templates found by query
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `ListCredentialTemplatesRequest`

ListVerificationTemplatesRequest¶

Request to list templates using a SQL query

Field	Type	Description
query	string	SQL query to execute. Example: `SELECT * FROM c WHERE c.name = 'Diploma'`
continuation_token	string	Token provided by previous `ListCredentialTemplatesResponse` if more data is available for query

ListVerificationTemplatesResponse¶

Field	Type	Description
templates	VerificationTemplateData[]	Templates found by query
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `ListVerificationTemplatesRequest`

SearchCredentialTemplatesRequest¶

Request to search templates using a SQL query

Field	Type	Description
query	string	SQL query to execute. Example: `SELECT * FROM c WHERE c.name = 'Diploma'`
continuation_token	string	Token provided by previous `SearchCredentialTemplatesResponse` if more data is available for query

SearchCredentialTemplatesResponse¶

Response to SearchCredentialTemplatesRequest

Field	Type	Description
items_json	string	Raw JSON data returned from query
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `SearchCredentialTemplatesRequest`

TemplateData¶

Credential Template

Field	Type	Description
id	string	Template ID
name	string	Template name
version	int32	Template version number
fields	TemplateData.FieldsEntry[]	Fields defined for the template
allow_additional_fields	bool	Whether credentials issued against this template may contain fields not defined by template
schema_uri	string	URI pointing to template JSON schema document
ecosystem_id	string	ID of ecosystem in which template resides
type	string	Template type (`VerifiableCredential`)
created_by	string	ID of template creator
date_created	string	Date when template was created as ISO 8601 utc string
title	string	Human-readable template title
description	string	Human-readable template description
field_ordering	TemplateData.FieldOrderingEntry[]	Map describing how to order and categorize the fields within the template. The key of this map is the field `name`.
apple_wallet_options	AppleWalletOptions	Options for rendering the template in Apple Wallet

TemplateData.FieldOrderingEntry¶

Field	Type	Description
key	string
value	FieldOrdering

TemplateData.FieldsEntry¶

Field	Type	Description
key	string
value	TemplateField

TemplateField¶

A field defined in a template

Field	Type	Description
title	string	Human-readable name of the field
description	string	Human-readable description of the field
optional	bool	Whether this field may be omitted when a credential is issued against the template
type	FieldType	The type of the field
uri_data	UriFieldData	How to deal with this URI field when rendering credential. Only use if `type` is `URI`.

TemplateFieldPatch¶

A patch to apply to an existing template field

Field	Type	Description
title	string	Human-readable name of the field
description	string	Human-readable description of the field
uri_data	UriFieldData	How to deal with this URI field when rendering credential. Only use if `type` is `URI`.

UpdateCredentialTemplateRequest¶

Request to update display information for a template

Field	Type	Description
id	string	ID of Template to update
title	string	New human-readable title of Template
description	string	New human-readable description of Template
fields	UpdateCredentialTemplateRequest.FieldsEntry[]	Fields to update within the Template
field_ordering	UpdateCredentialTemplateRequest.FieldOrderingEntry[]	New field ordering options. See documentation for template creation for usage information.
apple_wallet_options	AppleWalletOptions	New Apple Wallet configuration

UpdateCredentialTemplateRequest.FieldOrderingEntry¶

Field	Type	Description
key	string
value	FieldOrdering

UpdateCredentialTemplateRequest.FieldsEntry¶

Field	Type	Description
key	string
value	TemplateFieldPatch

UpdateCredentialTemplateResponse¶

Response to UpdateCredentialTemplateRequest

Field	Type	Description
updated_template	TemplateData	The Template after the update has been applied

UpdateVerificationTemplateRequest¶

Field	Type	Description
id	string	ID of Template to update
title	string	New human-readable title of Template
description	string	New human-readable description of Template
fields	UpdateVerificationTemplateRequest.FieldsEntry[]	Fields to update within the Template

UpdateVerificationTemplateRequest.FieldsEntry¶

Field	Type	Description
key	string
value	VerificationTemplateFieldPatch

UpdateVerificationTemplateResponse¶

Field	Type	Description
template	VerificationTemplateData

UriFieldData¶

Data pertaining to a URI Field

Field	Type	Description
mime_type	string	Expected MIME Type of content pointed to by URI. Can be generic (eg, "image/") or specific ("image/png"). Defaults to "application/octet-stream".
render_method	UriRenderMethod	How to display the URI value when rendering a credential.

VerificationTemplateData¶

Verification Template

Field	Type	Description
id	string	Template ID
name	string	Template name
version	int32	Template version number
fields	VerificationTemplateData.FieldsEntry[]	Fields defined for the template
credential_template_id	string	Source credential template, used for verifying that the specified `fields` are present in the credential template
ecosystem_id	string	ID of ecosystem in which template resides
type	string	Template type (`VerificationTemplate`)
created_by	string	ID of template creator
date_created	string	Date when template was created as ISO 8601 utc string
title	string	Human-readable template title
description	string	Human-readable template description

VerificationTemplateData.FieldsEntry¶

Field	Type	Description
key	string
value	VerificationTemplateField

VerificationTemplateField¶

A field defined in a template

Field	Type	Description
field_share_type	VerificationShareType	Whether this field may be omitted on proof creation
usage_policy	string	User-facing explanation of what is done with this data

TODO - Future work supporting proof conditionals/ranges/etc |

VerificationTemplateFieldPatch¶

A patch to apply to an existing template field

Field	Type	Description
field_share_type	VerificationShareType	Human-readable name of the field
usage_policy	string	User-facing explanation of what is done with this data

FieldType¶

Valid types for credential fields

Name	Number	Description
STRING	0
NUMBER	1
BOOL	2
DATETIME	4
URI	5

UriRenderMethod¶

How to display a URI value when rendering a credential.

Name	Number	Description
TEXT	0	Display URI as text
LINK	1	Display URI as a clickable link
INLINE_IMAGE	2	Display URI as an inline image. Only takes effect if the template field's MIME Type is an image type.

VerificationShareType¶

Name	Number	Description
OPTIONAL	0
REQUIRED	1

Top

services/verifiable-credentials/v1/verifiable-credentials.proto¶

Service - VerifiableCredential¶

Method Name	Request Type	Response Type	Description
IssueFromTemplate	IssueFromTemplateRequest	IssueFromTemplateResponse	Sign and issue a verifiable credential from a pre-defined template. This process will also add schema validation and revocation registry values to the credential.
CheckStatus	CheckStatusRequest	CheckStatusResponse	Check credential status in the revocation registry
UpdateStatus	UpdateStatusRequest	UpdateStatusResponse	Update credential status by setting the revocation value
CreateProof	CreateProofRequest	CreateProofResponse	Create a proof from a signed document that is a valid verifiable credential and contains a signature from which a proof can be derived.
VerifyProof	VerifyProofRequest	VerifyProofResponse	Verifies a proof by checking the signature value, and if possible schema validation, revocation status, and issuer status against a trust registry
Send	SendRequest	SendResponse	Sends a document directly to a user's email within the given ecosystem
CreateCredentialOffer	CreateCredentialOfferRequest	CreateCredentialOfferResponse	Create credential offer
AcceptCredential	AcceptCredentialRequest	AcceptCredentialResponse	Accept an offer to exchange a credential
RejectCredential	RejectCredentialRequest	RejectCredentialResponse	Reject an offer to exchange a credential

AcceptCredentialRequest¶

Field	Type	Description
document_json	string	The JSON document that contains the credential offer
item_id	string	The ID of the credential offer (Parameter ID inside the JSON document)

AcceptCredentialResponse¶

Field	Type	Description
item_id	string	The ID of the item in the wallet that contains the issued credential
document_json	string	The JSON document that contains the issued credential. This item is already stored in the wallet.

CheckStatusRequest¶

Request to check a credential's revocation status

Field	Type	Description
credential_status_id	string	Credential Status ID to check. This is not the same as the credential's ID.

CheckStatusResponse¶

Response to CheckStatusRequest

Field	Type	Description
revoked	bool	The credential's revocation status

CreateCredentialOfferRequest¶

Field	Type	Description
template_id	string	ID of template to use
values_json	string	JSON document string with keys corresponding to the fields of the template referenced by `template_id`
holder_binding	bool	If true, the credential will be issued with holder binding by specifying the holder DID in the credential subject
include_governance	bool	If true, the issued credential will contain an attestation of the issuer's membership in the ecosystem's Trust Registry.
generate_share_url	bool	If true, a short URL link will be generated that can be used to share the credential offer with the holder. This link will point to the credential offer in the wallet app.
signature_type	SignatureType	The type of signature to use when signing the credential. Defaults to `EXPERIMENTAL`.

CreateCredentialOfferResponse¶

Field	Type	Description
document_json	string	The JSON document that contains the credential offer
share_url	string	If requested, a URL that can be used to share the credential offer with the holder. This is a short URL that can be used in a QR code and will redirect the holder to the credential offer using the wallet app.

CreateProofRequest¶

Request to create a proof for a Verifiable Credential using public key tied to caller. Either item_id, or document_json may be provided, not both.

Field	Type	Description
reveal_document_json	string	A valid JSON-LD frame describing which fields should be revealed in the generated proof. If unspecified, all fields in the document will be revealed
reveal_template	RevealTemplateAttributes	Information about what sections of the document to reveal
verification_template_id	string	Id of verification template with which to construct the JSON-LD proof document
item_id	string	ID of wallet item stored in a Trinsic cloud wallet
document_json	string	A valid JSON-LD Verifiable Credential document string with an unbound signature. The proof will be derived from this document directly. The document will not be stored in the wallet.
use_verifiable_presentation	bool	Wrap the output in a verifiable presentation. If the credential used in the proof is bound to the holder DID, the output will always use a verifiable presentation and this field will be ignored.
nonce	bytes	Nonce value used to derive the proof. If not specified, a random nonce will be generated. This value may be represented in base64 format in the proof model.

CreateProofResponse¶

Response to CreateProofRequest

Field	Type	Description
proof_document_json	string	Valid JSON-LD proof for the specified credential

IssueFromTemplateRequest¶

Request to create and sign a JSON-LD Verifiable Credential from a template using public key tied to caller

Field	Type	Description
template_id	string	ID of template to use
values_json	string	JSON document string with keys corresponding to the fields of the template referenced by `template_id`
save_copy	bool	Save a copy of the issued credential to this user's wallet. This copy will only contain the credential data, but not the secret proof value. Issuers may use this data to keep track of the details for revocation status.
expiration_date	string	The ISO8601 expiration UTC date of the credential. This is a reserved field in the VC specification. If specified, the issued credential will contain an expiration date. https://www.w3.org/TR/vc-data-model/#expiration
include_governance	bool	If true, the issued credential will contain an attestation of the issuer's membership in the ecosystem's Trust Registry.
signature_type	SignatureType	The type of signature to use when signing the credential. Defaults to `EXPERIMENTAL`.

IssueFromTemplateResponse¶

Response to IssueFromTemplateRequest

Field	Type	Description
document_json	string	Verifiable Credential document, in JSON-LD form, constructed from the specified template and values; signed with public key tied to caller of `IssueFromTemplateRequest`

RejectCredentialRequest¶

Field	Type	Description
document_json	string	The JSON document that contains the credential offer
item_id	string	The ID of the credential offer (Parameter ID inside the JSON document)

RejectCredentialResponse¶

RevealTemplateAttributes¶

Field	Type	Description
template_attributes	string[]	A list of document attributes to reveal. If unset, all attributes will be returned.

SendRequest¶

Request to send a document to another user's wallet

Field	Type	Description
email	string	Email address of user to whom you'll send the item
wallet_id	string	Wallet ID of the recipient within the ecosystem
did_uri	string	DID URI of the recipient
phone_number	string	SMS of user to whom you'll send the item
send_notification	bool	Send email notification that credential has been sent to a wallet
document_json	string	JSON document to send to recipient

SendResponse¶

Response to SendRequest

UpdateStatusRequest¶

Request to update a credential's revocation status

Field	Type	Description
credential_status_id	string	Credential Status ID to update. This is not the same as the credential's ID.
revoked	bool	New revocation status of credential

UpdateStatusResponse¶

Response to UpdateStatusRequest

ValidationMessage¶

Result of a validation check on a proof

Field	Type	Description
is_valid	bool	Whether this validation check passed
messages	string[]	If validation failed, contains messages explaining why

VerifyProofRequest¶

Request to verify a proof

Field	Type	Description
proof_document_json	string	JSON-LD proof document string to verify

VerifyProofResponse¶

Response to VerifyProofRequest

Field	Type	Description
is_valid	bool	Whether all validations in `validation_results` passed
validation_results	VerifyProofResponse.ValidationResultsEntry[]	Results of each validation check performed, such as schema conformance, revocation status, signature, etc. Detailed results are provided for failed validations.

VerifyProofResponse.ValidationResultsEntry¶

Field	Type	Description
key	string
value	ValidationMessage

SignatureType¶

Name	Number	Description
UNSPECIFIED	0	The signature type is not specified. The experimental signature type will be used.
STANDARD	1	The signature type uses EdDSA with the Ed25519 curve (NIST compliant). This type of signature does not support selective disclosure of attributes.
EXPERIMENTAL	2	The signature type uses BBS signatures with BLS12-381 curve (experimental). This type of signature allows for selective disclosure of attributes.

Top

services/file-management/v1/file-management.proto¶

Service - FileManagement¶

Method Name	Request Type	Response Type	Description
UploadFile	UploadFileRequest	UploadFileResponse	Upload a file to Trinsic's CDN
GetFile	GetFileRequest	GetFileResponse	Fetch information about a file by its ID
DeleteFile	DeleteFileRequest	DeleteFileResponse	Delete a file by its ID
ListFiles	ListFilesRequest	ListFilesResponse	List files the calling account has uploaded
GetStorageStats	GetStorageStatsRequest	GetStorageStatsResponse	Get statistics about files uploaded by the calling account

DeleteFileRequest¶

Request to delete a file from Trinsic's CDN by ID

Field	Type	Description
id	string	ID of file to delete

DeleteFileResponse¶

Response to DeleteFileRequest. Empty payload.

File¶

Contains information about a file stored in Trinsic's CDN

Field	Type	Description
id	string	ID of file, generated randomly by Trinsic on upload
uploader_id	string	Wallet ID of uploader
size	uint32	Size, in bytes, of file
mime_type	string	Uploader-provided MIME type of file
uploaded	string	ISO 8601 timestamp of when file was uploaded to Trinsic
url	string	CDN URL of file

GetFileRequest¶

Request to fetch information about a stored file

Field	Type	Description
id	string	ID of file to fetch

GetFileResponse¶

Response to GetFileRequest

Field	Type	Description
file	File	File specified by `id` parameter of `GetFileRequest`.

GetStorageStatsRequest¶

Request to get statistics about files uploaded by this account

GetStorageStatsResponse¶

Response to GetStorageStatsRequest

Field	Type	Description
stats	StorageStats	Statistics about files uploaded by the calling account

ListFilesRequest¶

Request to list files

Field	Type	Description
query	string	Query to search with. If not specified, will return the most recent 100 files.
continuation_token	string	Token provided by previous `ListFilesRequest` if more data is available for query

ListFilesResponse¶

Response to ListFilesRequest

Field	Type	Description
files	File[]	Files found by query
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `ListFilesRequest`

StorageStats¶

Represents aggregate statistics of all files uploaded by a single issuer

Field	Type	Description
num_files	uint32	Number of files uploaded by this account
total_size	uint64	Sum total size of all files, in bytes

UploadFileRequest¶

Request to upload a file to Trinsic's CDN

Field	Type	Description
contents	bytes	Raw content of file
mime_type	string	MIME type describing file contents

UploadFileResponse¶

Response to UploadFileRequest

Field	Type	Description
uploaded_file	File	Information about newly-uploaded file

Top

services/provider/v1/provider.proto¶

Service - Provider¶

Method Name	Request Type	Response Type	Description
CreateEcosystem	CreateEcosystemRequest	CreateEcosystemResponse	Create new ecosystem and assign the authenticated user as owner
GetOberonKey	GetOberonKeyRequest	GetOberonKeyResponse	Returns the public key being used to create/verify oberon tokens
UpgradeDID	UpgradeDidRequest	UpgradeDidResponse	Upgrade a wallet's DID from `did:key` to another method
SearchWalletConfigurations	SearchWalletConfigurationsRequest	SearchWalletConfigurationResponse	Search for issuers/providers/verifiers in the current ecosystem

CreateEcosystemRequest¶

Request to create an ecosystem

Field	Type	Description
name	string	Globally unique name for the Ecosystem. This name will be part of the ecosystem-specific URLs and namespaces. Allowed characters are lowercase letters, numbers, underscore and hyphen. If not passed, ecosystem name will be auto-generated.
description	string	Ecosystem description
details	services.account.v1.AccountDetails	The account details of the owner of the ecosystem
domain	string	New domain URL

CreateEcosystemResponse¶

Response to CreateEcosystemRequest

Field	Type	Description
ecosystem	Ecosystem	Details of the created ecosystem
profile	services.account.v1.AccountProfile	Account profile for auth of the owner of the ecosystem
confirmation_method	services.account.v1.ConfirmationMethod	Indicates if confirmation of account is required.

Ecosystem¶

Details of an ecosystem

Field	Type	Description
id	string	URN of the ecosystem
name	string	Globally unique name for the ecosystem
description	string	Ecosystem description

EcosystemInfoRequest¶

Request to fetch information about an ecosystem

EcosystemInfoResponse¶

Response to InfoRequest

Field	Type	Description
ecosystem	Ecosystem	Ecosystem corresponding to current ecosystem in the account token

GetOberonKeyRequest¶

Request to fetch the Trinsic public key used to verify authentication token validity

GetOberonKeyResponse¶

Response to GetOberonKeyRequest

Field	Type	Description
key	string	Oberon Public Key as RAW base64-url encoded string

IndyOptions¶

Options for creation of DID on the SOV network

Field	Type	Description
network	IndyOptions.IndyNetwork	SOV network on which DID should be published

IonOptions¶

Options for creation of DID on the ION network

Field	Type	Description
network	IonOptions.IonNetwork	ION network on which DID should be published

SearchWalletConfigurationResponse¶

Field	Type	Description
results	WalletConfiguration[]	Results matching the search query
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `SearchRequest`

SearchWalletConfigurationsRequest¶

Search for issuers/holders/verifiers

Field	Type	Description
query_filter	string	SQL filter to execute. `SELECT * FROM c WHERE [queryFilter]`
continuation_token	string	Token provided by previous `SearchResponse` if more data is available for query

UpgradeDidRequest¶

Request to upgrade a wallet

Field	Type	Description
email	string	Email address of account to upgrade. Mutually exclusive with `walletId` and `didUri`.
wallet_id	string	Wallet ID of account to upgrade. Mutually exclusive with `email` and `didUri`.
did_uri	string	DID URI of the account to upgrade. Mutually exclusive with `email` and `walletId`.
method	services.common.v1.SupportedDidMethod	DID Method to which wallet should be upgraded
ion_options	IonOptions	Configuration for creation of DID on ION network
indy_options	IndyOptions	Configuration for creation of DID on INDY network

UpgradeDidResponse¶

Response to UpgradeDIDRequest

Field	Type	Description
did	string	New DID of wallet

WalletConfiguration¶

Strongly typed information about wallet configurations

Field	Type	Description
name	string	Name/description of the wallet
email	string	Deprecated. Deprecated and will be removed on August 1, 2023 -- use external_identities. This field is set to the first email address present in `external_identities`, if any.
sms	string	Deprecated. Deprecated -- use external_identities
wallet_id	string
public_did	string	The DID of the wallet
config_type	string
auth_tokens	services.account.v1.WalletAuthToken[]	List of active authentication tokens for this wallet. This list does not contain the issued token, only metadata such as ID, description, and creation date.
external_identity_ids	string[]	Deprecated. List of external identity IDs (email addresses, phone numbers, etc.) associated with this wallet. This is deprecated; use `external_identities` instead.
ecosystem_id	string	Ecosystem in which this wallet is contained.
description	string
external_identities	WalletExternalIdentity[]	List of external identities associated with this wallet.

WalletExternalIdentity¶

An external identity (email address, phone number, etc.) associated with a wallet for authentication purposes.

Field	Type	Description
provider	IdentityProvider	The type of this identity (whether this identity is an email address, phone number, etc.)
id	string	The actual email address/phone number/etc. for this identity

IdentityProvider¶

Name	Number	Description
Unknown	0	Identity provider is unknown
Email	1	Identity provider is email
Phone	2	Identity provider is phone
Passkey	3	Identity provider is passkey (WebAuthn) -- for Trinsic internal use only
TrinsicAuthenticator	4	Identity provider is passkey using Trinsic Authenticator for mobile phones

IndyOptions.IndyNetwork¶

Name	Number	Description
Danube	0
SovrinBuilder	1
SovrinStaging	2
Sovrin	3
IdUnionTest	4
IdUnion	5
IndicioTest	6
IndicioDemo	7
Indicio	8

IonOptions.IonNetwork¶

Name	Number	Description
TestNet	0
MainNet	1

Top

services/provider/v1/access-management.proto¶

Service - AccessManagement¶

Access Management service provides methods to manage access to ecosystem resources such by assigning roles and permissions to wallet accounts

Method Name	Request Type	Response Type	Description
AddRoleAssignment	AddRoleAssignmentRequest	AddRoleAssignmentResponse	Adds a role assignment to an account
RemoveRoleAssignment	RemoveRoleAssignmentRequest	RemoveRoleAssignmentResponse	Removes a role assignment from the account
ListRoleAssignments	ListRoleAssignmentsRequest	ListRoleAssignmentsResponse	List the role assignments for the given account
ListAvailableRoles	ListAvailableRolesRequest	ListAvailableRolesResponse	List the roles available in the ecosystem

AddRoleAssignmentRequest¶

Role management

Field	Type	Description
role	string	Role to assign
email	string	Email address of account to assign role. Mutually exclusive with `walletId` and `didUri`.
wallet_id	string	Wallet ID of account to assign role to. Mutually exclusive with `email` and `didUri`.
did_uri	string	DID URI of the account to assign role. Mutually exclusive with `email` and `walletId`.

AddRoleAssignmentResponse¶

ListAvailableRolesRequest¶

Request to fetch the available roles in the current ecosystem

ListAvailableRolesResponse¶

Field	Type	Description
roles	string[]	List of roles

ListRoleAssignmentsRequest¶

Request to fetch the list of roles assigned to the current account

Field	Type	Description
email	string	Email address of account to list roles. Mutually exclusive with `walletId` and `didUri`.
wallet_id	string	Wallet ID of account to list roles. Mutually exclusive with `email` and `didUri`.
did_uri	string	DID URI of the account to list roles. Mutually exclusive with `email` and `walletId`.

ListRoleAssignmentsResponse¶

Field	Type	Description
roles	string[]	List of roles

RemoveRoleAssignmentRequest¶

Field	Type	Description
role	string	Role to unassign
email	string	Email address of account to unassign role. Mutually exclusive with `walletId` and `didUri`.
wallet_id	string	Wallet ID of account to unassign role. Mutually exclusive with `email` and `didUri`.
did_uri	string	DID URI of the account to unassign role. Mutually exclusive with `email` and `walletId`.

RemoveRoleAssignmentResponse¶

Top

services/common/v1/common.proto¶

Nonce¶

Nonce used to generate an oberon proof

Field	Type	Description
timestamp	int64	UTC unix millisecond timestamp the request was made
request_hash	bytes	blake3256 hash of the request body

TrinsicClientOptions¶

Field	Type	Description
server_endpoint	string	Trinsic API endpoint. Defaults to `prod.trinsic.cloud`
server_port	int32	Trinsic API port; defaults to `443`
server_use_tls	bool	Whether TLS is enabled between SDK and Trinsic API; defaults to `true`
auth_token	string	Authentication token for SDK calls; defaults to empty string (unauthenticated)

OrderDirection¶

The direction to order results

Name	Number	Description
ASCENDING	0
DESCENDING	1

ResponseStatus¶

Name	Number	Description
SUCCESS	0
WALLET_ACCESS_DENIED	10
WALLET_EXISTS	11
ITEM_NOT_FOUND	20
SERIALIZATION_ERROR	200
UNKNOWN_ERROR	100

SupportedDidMethod¶

Enum of all supported DID Methods https://docs.godiddy.com/en/supported-methods

Name	Number	Description
KEY	0	The did:key method -- all wallets use this by default
ION	1	The did:ion method -- Sidetree implementation on top of Bitcoin by Microsoft
INDY	2	The did:sov method -- Hyperledger Indy based by Sovrin Foundation

Top

services/trust-registry/v1/trust-registry.proto¶

Service - TrustRegistry¶

Method Name	Request Type	Response Type	Description
RegisterMember	RegisterMemberRequest	RegisterMemberResponse	Register an authoritative issuer for a credential schema
UnregisterMember	UnregisterMemberRequest	UnregisterMemberResponse	Removes an authoritative issuer for a credential schema from the trust registry
GetMemberAuthorizationStatus	GetMemberAuthorizationStatusRequest	GetMemberAuthorizationStatusResponse	Fetch the status of a member for a given credential schema in a trust registry
ListAuthorizedMembers	ListAuthorizedMembersRequest	ListAuthorizedMembersResponse	Fetch the ecosystem's authorized issuers and the respective templates against which it can issue
GetMember	GetMemberRequest	GetMemberResponse	Get member for a given did in a trust registry

AuthorizedMember¶

Field	Type	Description
did	string
authorized_member_schemas	AuthorizedMemberSchema[]

AuthorizedMemberSchema¶

Field	Type	Description
schema_uri	string
status	string
status_details	string
valid_from	uint64
valid_until	uint64

GetMemberAuthorizationStatusRequest¶

Request to fetch member status in Trust Registry for a specific credential schema.

Field	Type	Description
did_uri	string	DID URI of member
schema_uri	string	URI of credential schema associated with member

GetMemberAuthorizationStatusResponse¶

Response to GetMemberAuthorizationStatusRequest

Field	Type	Description
status	RegistrationStatus	Status of member for given credential schema

GetMemberRequest¶

Request to get a member of the Trust Registry

Field	Type	Description
did_uri	string	DID URI of member to get
wallet_id	string	Trinsic Wallet ID of member to get
email	string	Email address of member to get. Must be associated with an existing Trinsic account.

GetMemberResponse¶

Response to GetMemberAuthorizationStatusRequest

Field	Type	Description
authorized_member	AuthorizedMember	Member for given did in given framework

ListAuthorizedMembersRequest¶

Field	Type	Description
schema_uri	string	id of schema that needs to be checked
continuation_token	string	Token to fetch next set of results, from previous `ListAuthorizedMembersResponse`

ListAuthorizedMembersResponse¶

Response to ListAuthorizedMembersRequest

Field	Type	Description
authorized_members	AuthorizedMember[]	JSON string containing array of resultant objects
has_more_results	bool	Whether more data is available to fetch for query
continuation_token	string	Token to fetch next set of results via `ListAuthorizedMembersRequest`

RegisterMemberRequest¶

Request to register a member as a valid issuer of a specific credential schema. Only one of did_uri, wallet_id, or email may be specified.

Field	Type	Description
did_uri	string	DID URI of member to register
wallet_id	string	Trinsic Wallet ID of member to register
email	string	Email address of member to register. Must be associated with an existing Trinsic account.
schema_uri	string	URI of credential schema to register member as authorized issuer of
valid_from_utc	uint64	Unix Timestamp member is valid from. Member will not be considered valid before this timestamp.
valid_until_utc	uint64	Unix Timestamp member is valid until. Member will not be considered valid after this timestamp.

RegisterMemberResponse¶

Response to RegisterMemberRequest

UnregisterMemberRequest¶

Request to unregister a member as a valid issuer of a specific credential schema. Only one of did_uri, wallet_id, or email may be specified. The URI of the credential schema must be specified.

Field	Type	Description
did_uri	string	DID URI of member to unregister
wallet_id	string	Trinsic Wallet ID of member to unregister
email	string	Email address of member to unregister. Must be associated with an existing Trinsic account.
schema_uri	string	URI of credential schema to unregister member as authorized issuer of

UnregisterMemberResponse¶

Response to UnregisterMemberRequest

RegistrationStatus¶

Name	Number	Description
CURRENT	0	Member is currently authorized, as of the time of the query
EXPIRED	1	Member's authorization has expired
TERMINATED	2	Member has voluntarily ceased Issuer role under the specific EGF
REVOKED	3	Member authority under specific EGF was terminated by the governing authority
NOT_FOUND	10	Member is not associated with given credential schema in the EGF

Top

services/account/v1/account.proto¶

AccountDetails¶

Account registration details

Field	Type	Description
name	string	Account name
email	string	Deprecated. Email address of account.
sms	string	Deprecated. SMS number including country code

AccountProfile¶

Device profile containing sensitive authentication data. This information should be stored securely

Field	Type	Description
profile_type	string	The type of profile, used to differentiate between protocol schemes or versions
auth_data	bytes	Auth data containg information about the current device access
auth_token	bytes	Secure token issued by server used to generate zero-knowledge proofs
protection	TokenProtection	Token security information about the token. If token protection is enabled, implementations must supply protection secret before using the token for authentication.

TokenProtection¶

Token protection info

Field	Type	Description
enabled	bool	Indicates if token is protected using a PIN, security code, HSM secret, etc.
method	ConfirmationMethod	The method used to protect the token

WalletAuthToken¶

Information about authentication tokens for a wallet

Field	Type	Description
id	string	Unique identifier for the token. This field will match the `DeviceId` in the WalletAuthData
description	string	Device name/description
date_created	string	Date when the token was created in ISO 8601 format

ConfirmationMethod¶

Confirmation method type for two-factor workflows

Name	Number	Description
None	0	No confirmation required
Email	1	Email confirmation required
Sms	2	SMS confirmation required
ConnectedDevice	3	Confirmation from a connected device is required
Other	10	Third-party method of confirmation is required

Top

services/universal-wallet/v1/universal-wallet.proto¶

Service - UniversalWallet¶

Service for managing wallets

Method Name	Request Type	Response Type	Description
GetItem	GetItemRequest	GetItemResponse	Retrieve an item from the wallet with a given item identifier
Search	SearchRequest	SearchResponse	Search the wallet using a SQL syntax
InsertItem	InsertItemRequest	InsertItemResponse	Insert an item into the wallet
UpdateItem	UpdateItemRequest	UpdateItemResponse	Update an item in the wallet
DeleteItem	DeleteItemRequest	DeleteItemResponse	Delete an item from the wallet permanently
DeleteWallet	DeleteWalletRequest	DeleteWalletResponse	Delete a wallet and its credentials
CreateWallet	CreateWalletRequest	CreateWalletResponse	Create a new wallet and generate an auth token for access
GetWalletInfo	GetWalletInfoRequest	GetWalletInfoResponse	Retrieve wallet details and configuration
GetMyInfo	GetMyInfoRequest	GetMyInfoResponse	Retrieve wallet details and configuration about the currently authenticated wallet
GetWalletFromExternalIdentity	GetWalletFromExternalIdentityRequest	GetWalletFromExternalIdentityResponse	Retrieve information from an ecosystem wallet by searching for its external identity (email or phone)
GenerateAuthToken	GenerateAuthTokenRequest	GenerateAuthTokenResponse	Generate new token for a given wallet and add it to the collection of known auth tokens. This endpoint requires authentication and will return a new token ID and auth token. Use this endpoint if you want to authorize another device, without having to share your existing auth token.
RevokeAuthToken	RevokeAuthTokenRequest	RevokeAuthTokenResponse	Revokes a previously issued auth token and updates the collection of known auth tokens. This endpoint requires authentication.
AddExternalIdentityInit	AddExternalIdentityInitRequest	AddExternalIdentityInitResponse	Add new external identity to the current wallet, such as email, sms, ethereum address, etc. This identity ownership must be confirmed using `AddIdentityConfirm` via OTP, signature, etc.
AddExternalIdentityConfirm	AddExternalIdentityConfirmRequest	AddExternalIdentityConfirmResponse	Confirm identity added to the current wallet using `AddExternalIdentityInit`
RemoveExternalIdentity	RemoveExternalIdentityRequest	RemoveExternalIdentityResponse	Remove an external identity from the current wallet
AuthenticateInit	AuthenticateInitRequest	AuthenticateInitResponse	Sign-in to an already existing wallet, using an identity added that was previously registered This endpoint does not require authentication, and will return a challenge to be signed or verified
AuthenticateConfirm	AuthenticateConfirmRequest	AuthenticateConfirmResponse	Confirm sign-in to an already existing wallet and return authentication token
AuthenticateResendCode	AuthenticateResendCodeRequest	AuthenticateResendCodeResponse	Resend previous authentication code
ListWallets	ListWalletsRequest	ListWalletsResponse	List all wallets in the ecosystem
ListByVerificationTemplate	ListByVerificationTemplateRequest	ListByVerificationTemplateResponse	List credentials which match a given verification template

AddExternalIdentityConfirmRequest¶

Field	Type	Description
challenge	string	The challenge received from the `AddExternalIdentityInit` endpoint
response	string	The response to the challenge. If using Email or Phone, this is the OTP code sent to the user's email or phone

AddExternalIdentityConfirmResponse¶

AddExternalIdentityInitRequest¶

Field	Type	Description
identity	string	The user identity to add to the wallet This can be an email address or phone number (formatted as +[country code][phone number])
provider	services.provider.v1.IdentityProvider	The type of identity provider, like EMAIL or PHONE

AddExternalIdentityInitResponse¶

Field	Type	Description
challenge	string	Challenge or reference to the challenge to be used in the `AddExternalIdentityConfirm` endpoint

AuthenticateConfirmRequest¶

Field	Type	Description
challenge	string	The challenge received from the `AcquireAuthTokenInit` endpoint
response	string	The response to the challenge. If using Email or Phone, this is the OTP code sent to the user's email or phone

AuthenticateConfirmResponse¶

Field	Type	Description
auth_token	string	Auth token for the wallet

AuthenticateInitRequest¶

Field	Type	Description
identity	string	Identity to add to the wallet
provider	services.provider.v1.IdentityProvider	Identity provider
ecosystem_id	string	Ecosystem ID to which the wallet belongs

AuthenticateInitResponse¶

Field	Type	Description
challenge	string	The challenge received from the `AcquireAuthTokenInit` endpoint Pass this challenge back to the `AcquireAuthTokenConfirm` endpoint

AuthenticateResendCodeRequest¶

Field	Type	Description
challenge	string	Challenge for the code you want resent.

AuthenticateResendCodeResponse¶

CreateWalletRequest¶

Field	Type	Description
ecosystem_id	string	Ecosystem ID of the wallet to create
description	string	Wallet name or description. Use this field to add vendor specific information about this wallet, such as email, phone, internal ID, or anything you'd like to associate with this wallet. This field is searchable.
identity	CreateWalletRequest.ExternalIdentity	Optional identity to add to the wallet (email or sms). Use this field when inviting participants into an ecosystem. If this field is set, an auth token will not be sent in the response.

CreateWalletRequest.ExternalIdentity¶

Field	Type	Description
identity	string	The user identity to add to the wallet This can be an email address or phone number (formatted as +[country code][phone number])
provider	services.provider.v1.IdentityProvider	The type of identity provider, like EMAIL or PHONE

CreateWalletResponse¶

Field	Type	Description
auth_token	string	Auth token for the newly created wallet
token_id	string	Token ID of the newly generated token
wallet	services.provider.v1.WalletConfiguration	Wallet configuration

DeleteItemRequest¶

Request to delete an item in a wallet

Field	Type	Description
item_id	string	ID of item to delete

DeleteItemResponse¶

Response to DeleteItemRequest

DeleteWalletRequest¶

Request to delete a wallet

Field	Type	Description
email	string	Email address of account to delete. Mutually exclusive with `walletId` and `didUri`.
wallet_id	string	Wallet ID of account to delete. Mutually exclusive with `email` and `didUri`.
did_uri	string	DID URI of the account to delete. Mutually exclusive with `email` and `walletId`.

DeleteWalletResponse¶

Response to DeleteWalletRequest. Empty payload.

GenerateAuthTokenRequest¶

Field	Type	Description
wallet_id	string
token_description	string

GenerateAuthTokenResponse¶

Field	Type	Description
token_id	string
auth_token	string

GetItemRequest¶

Request to fetch an item from wallet

Field	Type	Description
item_id	string	ID of item in wallet

GetItemResponse¶

Response to GetItemRequest

Field	Type	Description
item_json	string	Item data as a JSON string
item_type	string	Type of item specified when item was inserted into wallet

GetMyInfoRequest¶

Request to retrieve wallet information about the currently authenticated wallet

GetMyInfoResponse¶

Response to GetMyInfoRequest

Field	Type	Description
wallet	services.provider.v1.WalletConfiguration	Wallet configuration

GetWalletFromExternalIdentityRequest¶

Field	Type	Description
identity	services.provider.v1.WalletExternalIdentity

GetWalletFromExternalIdentityResponse¶

Response to GetWalletFromExternalIdentityRequest

Field	Type	Description
wallet	services.provider.v1.WalletConfiguration	Wallet configuration

GetWalletInfoRequest¶

Request to retrieve wallet information about a given wallet identified by its wallet ID

Field	Type	Description
wallet_id	string	Wallet ID of the wallet to retrieve

GetWalletInfoResponse¶

Response to GetWalletInfoRequest

Field	Type	Description
wallet	services.provider.v1.WalletConfiguration	Wallet configuration

InsertItemRequest¶

Request to insert a JSON document into a wallet

Field	Type	Description
item_json	string	Document to insert; must be stringified JSON
item_type	string	Item type (ex. "VerifiableCredential")

InsertItemResponse¶

Response to InsertItemRequest

Field	Type	Description
item_id	string	ID of item inserted into wallet

ListByVerificationTemplateRequest¶

Request to list templates by

Field	Type	Description
verification_template_id	string	ID of verification template to list matching credentials
continuation_token	string	Token provided by previous `ListCredentialTemplatesResponse` if more data is available for query

ListByVerificationTemplateResponse¶

Response to ListByVerificationTemplateRequest

Field	Type	Description
items	string[]	Array of query results, as JSON strings
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `ListByVerificationTemplateRequest`

ListWalletsRequest¶

Field	Type	Description
filter	string

ListWalletsResponse¶

Field	Type	Description
wallets	services.provider.v1.WalletConfiguration[]

RemoveExternalIdentityRequest¶

Field	Type	Description
identity	string	The user identity to remove from the wallet This can be an email address or phone number (formatted as +[country code][phone number])

RemoveExternalIdentityResponse¶

RevokeAuthTokenRequest¶

Request to revoke a previously issued auth token

Field	Type	Description
wallet_id	string	Wallet ID of the wallet to from which to revoke the token
token_id	string	Token ID of the token to revoke

RevokeAuthTokenResponse¶

SearchRequest¶

Request to search items in wallet

Field	Type	Description
query	string	SQL Query to execute against items in wallet
continuation_token	string	Token provided by previous `SearchResponse` if more data is available for query

SearchResponse¶

Response to SearchRequest

Field	Type	Description
items	string[]	Array of query results, as JSON strings
has_more_results	bool	Whether more results are available for this query via `continuation_token`
continuation_token	string	Token to fetch next set of results via `SearchRequest`

UpdateItemRequest¶

Request to update item in wallet

Field	Type	Description
item_id	string	ID of item in wallet
item_type	string	Item type (ex. "VerifiableCredential")

UpdateItemResponse¶

Response to UpdateItemRequest

Top

services/connect/v1/connect.proto¶

Service - Connect¶

The Connect service provides access to Trinsic Connect, a reusable identity verification service.

Method Name	Request Type	Response Type	Description
CreateSession	CreateSessionRequest	CreateSessionResponse	Create an IDVSession
CancelSession	CancelSessionRequest	CancelSessionResponse	Cancel an IDVSession
GetSession	GetSessionRequest	GetSessionResponse	Get an IDVSession
ListSessions	ListSessionsRequest	ListSessionsResponse	List IDVSessions created by the calling wallet
HasValidCredential	HasValidCredentialRequest	HasValidCredentialResponse	Checks if the identity provided in the request has a wallet containing a valid reusable credential

CancelSessionRequest¶

Request to cancel an Identity Verification Session

Field	Type	Description
idv_session_id	string	The ID of the IDVSession to cancel

CancelSessionResponse¶

Response to CancelIDVSessionRequest

Field	Type	Description
session	IDVSession	The IDVSession in its current state after cancellation

CreateSessionRequest¶

Request to create an Identity Verification Session

Field	Type	Description
verifications	RequestedVerification[]	Array of verifications to perform
debug_information	CreateSessionRequest.DebugInformationEntry[]	Debugging information used to help diagnose issues

CreateSessionRequest.DebugInformationEntry¶

Field	Type	Description
key	string
value	string

CreateSessionResponse¶

Response to CreateIDVSessionRequest

Field	Type	Description
session	IDVSession	The created IDVSession

CredentialRequestData¶

Field	Type	Description
type	VerificationType	The type of verification for which the credential can be used

Name of the IDV issuer |

GetSessionRequest¶

Request to get an IDVSession

Field	Type	Description
idv_session_id	string	The ID of the IDVSession to get

GetSessionResponse¶

Response to GetIDVSessionRequest

Field	Type	Description
session	IDVSession	The IDVSession

GovernmentIDFields¶

Selection of fields to retrieve from a Government ID. All fields default to false unless explicitly set to true.

Field	Type	Description
id_number	bool	ID number of the underlying identity document
given_name	bool	Given ("first") name of the document holder
family_name	bool	Family ("last") name of the document holder
address	bool	Full address of the document holder
date_of_birth	bool	Date of birth of the document holder
country	bool	ISO3 country code of the document
issue_date	bool	Issuance date of the document
expiration_date	bool	Expiration date date of the document

GovernmentIDOptions¶

Options for a Verification of type GOVERNMENT_ID

Field	Type	Description
fields	GovernmentIDFields	The fields to retrieve from the Government ID. If this object is not set, all fields will be retrieved.

HasValidCredentialRequest¶

Request to preemptively check if an identity has a valid reusable credential

Field	Type	Description
identity	services.universalwallet.v1.CreateWalletRequest.ExternalIdentity	The identity used to find a credential
credential_request_data	CredentialRequestData	The criteria used to find a valid credential

HasValidCredentialResponse¶

Response to HasValidCredentialRequest

Field	Type	Description
has_valid_credential	bool	Whether the identity has a valid credential

IDVSession¶

An Identity Verification Session

Field	Type	Description
id	string	The ID of the IDVSession.
client_token	string	The Client Token for this IDVSession. This should be passed to your frontend to initiate the IDV flow using Trinsic's Web SDK.
state	IDVSessionState	State of the IDVSession
verifications	IDVSession.VerificationsEntry[]	The actual Verifications to perform in this IDV flow
fail_code	SessionFailCode	The reason for the IDVSession's failure. Only set if `state` is `IDV_FAILED`.
result_vp	string	The resultant signed VP combining the results of all verifications
created	fixed64	The unix timestamp, in seconds, that this IDVSession was created
updated	fixed64	The unix timestamp, in seconds, that this IDVSession's `state` was last updated

IDVSession.VerificationsEntry¶

Field	Type	Description
key	string
value	Verification

ListSessionsRequest¶

Request to list all IDVSessions you've created

Field	Type	Description
order_by	SessionOrdering	The field by which sessions should be sorted. Defaults to `CREATED`.
order_direction	services.common.v1.OrderDirection	The order in which sessions should be sorted. Defaults to `ASCENDING`.
page_size	int32	The number of results to return per page. Must be between `1` and `10`, inclusive. Defaults to `10`.
page	int32	The page index of results to return. Starts at `1`. Defaults to `1`.

ListSessionsResponse¶

Response to ListIDVSessionsRequest

Field	Type	Description
sessions	IDVSession[]	The sessions you've created
total	int32	The total number of sessions you've created
more	bool	If `true`, this is not the last page of results. If `false`, this is the last page of results.

NormalizedGovernmentIdData¶

Field	Type	Description
id_number	string	The ID number of the underlying identity document
given_name	string	Given ("first") name of the document holder
family_name	string	Family ("last") name of the document holder
address	string	Full address of the document holder
date_of_birth	string	Date of birth of the document holder
country	string	ISO3 country code of the document
issue_date	string	Issuance date of the document
expiration_date	string	Expiration date date of the document

RequestedVerification¶

A verification to perform in an IDV flow

Field	Type	Description
type	VerificationType	The type of verification to perform
government_id_options	GovernmentIDOptions	Options for a Verification of type `GOVERNMENT_ID`

Verification¶

A Verification that is part of an IDVSession

Field	Type	Description
id	string	The ID of the verification
type	VerificationType	The type of verification (driver's license, passport, proof of address, etc)
state	VerificationState	The state of the verification
fail_code	VerificationFailCode	The reason for the Verification's failure. Only set if `state` is `VERIFICATION_FAILED`.
reused	bool	Whether this was a reused (true) or fresh (false) verification. If `state` is not `VERIFICATION_SUCCESS`, this field is `false` and does not convey useful information.
begun	fixed64	The unix timestamp, in seconds, when this verification was begun by the user -- or `0` if not yet begun.
updated	fixed64	The unix timestamp, in seconds, when this verification last changed state -- or `0` if it has not yet begun.
government_id_options	GovernmentIDOptions	The Government ID options for this Verification. Only set if this Verification is of type `GOVERNMENT_ID`.
normalized_government_id_data	NormalizedGovernmentIdData	Normalized output for manual parsing and usage for this verification Only set if this Verification is of type `GOVERNMENT_ID` and has succeeded.

IDVSessionState¶

The states a VerificationSession can be in

Name	Number	Description
IDV_CREATED	0	Session has been created, but not yet shown to user
IDV_INITIATED	1	Session has been shown to user (iframe / popup opened), but user has not yet logged in.
IDV_AUTHENTICATING	2	User has entered their phone number, but not yet authenticated with the code sent via SMS
IDV_IN_PROGRESS	3	User has been authenticated and is performing identity verification
IDV_SUCCESS	4	Session was completed successfully and IDV data is available to RP
IDV_FAILED	5	The session failed; reason is present in `fail_code`.

SessionFailCode¶

The specific reason an IDVSession is in the Failed state

Name	Number	Description
SESSION_FAIL_NONE	0	The Session is not in a failure state.
SESSION_FAIL_INTERNAL	1	An internal Trinsic error caused this session to fail
SESSION_FAIL_VERIFICATION_FAILED	2	The session failed because one or more of the verifications failed. The reason for the failure is present in the `fail_reason` field of the relevant `Verification` object(s).
SESSION_FAIL_AUTHENTICATION	3	The session failed because the user failed to authenticate with their phone number too many times.
SESSION_FAIL_EXPIRED	4	The session expired
SESSION_FAIL_USER_CANCELED	5	The user canceled / rejected the session
SESSION_FAIL_RP_CANCELED	6	The RP canceled the session

SessionOrdering¶

Controls how sessions are ordered in ListSessions

Name	Number	Description
CREATED	0	Order sessions according to when they were created
UPDATED	1	Order sessions according to when they last changed state
STATE	2	Order sessions according to their numerical state

VerificationFailCode¶

The specific reason a Verification is in the Failed state

Name	Number	Description
VERIFICATION_FAIL_NONE	0	The verification is not in a failure state
VERIFICATION_FAIL_INTERNAL	1	An internal Trinsic error caused this verification to fail
VERIFICATION_FAIL_INVALID_IMAGE	2	The image(s) provided for this verification were either too low-quality, not of the correct type, or otherwise unable to be processed. This failure reason is non-terminal; the user is able to retry the verification.
VERIFICATION_FAIL_INAUTHENTIC	3	The identity data/images provided are suspected to be inauthentic, fraudulent, or forged.
VERIFICATION_FAIL_UNSUPPORTED_DOCUMENT	4	The document provided is either of an unsupported type, or from an unsupported country.

VerificationState¶

The states an individual Verification can be in

Name	Number	Description
VERIFICATION_PENDING	0	This verification has not yet been performed in the flow
VERIFICATION_PENDING_REUSE	1	This verification has been started by the user, and can be reused from a previous verification, but the user has not yet decided whether to reuse it.
VERIFICATION_STARTED	2	This verification has been started by the user, but not yet completed
VERIFICATION_SUCCESS	3	This verification has been successfully completed
VERIFICATION_FAILED	4	This verification has failed

VerificationType¶

The type of verification to perform

Name	Number	Description
GOVERNMENT_ID	0	Government-issued ID (driver's license, passport, etc)

Scalar Value Types¶

.proto Type	Notes	C++	Java	Python	Go	C#	PHP
double		double	double	float	float64	double	float
float		float	float	float	float32	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
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
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer
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
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string
sfixed32	Always four bytes.	int32	int	int	int32	int	integer
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string
bool		bool	boolean	boolean	bool	bool	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string