Protocol Documentation¶

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

sdk/options/v1/options.proto¶

ServiceOptions¶

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/account/v1/account.proto¶

Service - Account¶

Method Name	Request Type	Response Type	Description
SignIn	SignInRequest	SignInResponse	Sign in to an already existing account
Login	LoginRequest	LoginResponse	Begin login flow for specified account, creating one if it does not already exist
LoginConfirm	LoginConfirmRequest	LoginConfirmResponse	Finalize login flow with two-factor confirmation code
Info	AccountInfoRequest	AccountInfoResponse	Get account information
AuthorizeWebhook	AuthorizeWebhookRequest	AuthorizeWebhookResponse	Authorize Ecosystem to receive webhook events

AccountDetails¶

Account registration details

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

AccountEcosystem¶

Deprecated

Field	Type	Description
id	string
name	string
description	string
uri	string

AccountInfoRequest¶

Request for information about the account used to make the request

AccountInfoResponse¶

Information about the account used to make the request

Field	Type	Description
details	AccountDetails	The account details associated with the calling request context
ecosystems	AccountEcosystem[]	Deprecated. Use `ecosystem_id` instead
wallet_id	string	The wallet ID associated with this account
device_id	string	The device ID associated with this account session
ecosystem_id	string	The ecosystem ID within which this account resides
public_did	string	The public DID associated with this account. This DID is used as the `issuer` when signing verifiable credentials

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.

AuthorizeWebhookRequest¶

Request to authorize Ecosystem provider to receive webhooks for events which occur on this wallet.

Field	Type	Description
events	string[]	Events to authorize access to. Default is "*" (all events)

AuthorizeWebhookResponse¶

Response to AuthorizeWebhookRequest

LoginConfirmRequest¶

Request to finalize login flow

Field	Type	Description
challenge	bytes	Challenge received from `Login`
confirmation_code_hashed	bytes	Two-factor confirmation code sent to account email or phone, hashed using Blake3. Our SDKs will handle this hashing process for you.

LoginConfirmResponse¶

Response to LoginConfirmRequest

Field	Type	Description
profile	AccountProfile	Profile response; must be unprotected using unhashed confirmation code. Our SDKs will handle this process for you, and return to you an authentication token string.

LoginRequest¶

Request to begin login flow

Field	Type	Description
email	string	Email address of account. If unspecified, an anonymous account will be created.
invitation_code	string	Deprecated. DEPRECATED, will be removed April 1st 2023 Invitation code associated with this registration
ecosystem_id	string	ID of Ecosystem to sign into. Ignored if `invitation_code` is passed.

LoginResponse¶

Response to LoginRequest

Field	Type	Description
challenge	bytes	Random byte sequence unique to this login request. If present, two-factor confirmation of login is required. Must be sent back, unaltered, in `LoginConfirm`.
profile	AccountProfile	Account profile response. If present, no confirmation of login is required.

SignInRequest¶

Request for creating or signing into an account

Field	Type	Description
details	AccountDetails	Account registration details
invitation_code	string	Deprecated. DEPRECATED, will be removed April 1st 2023 Invitation code associated with this registration
ecosystem_id	string	ID of Ecosystem to use Ignored if `invitation_code` is passed

SignInResponse¶

Response for creating new account This object will indicate if a confirmation code was sent to one of the users two-factor methods like email, SMS, etc.

Field	Type	Description
confirmation_method	ConfirmationMethod	Indicates if confirmation of account is required.
profile	AccountProfile	Contains authentication data for use with the current device. This object must be stored in a secure place. It can also be protected with a PIN, but this is optional. See the docs at https://docs.trinsic.id for more information on working with authentication data.

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

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

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	AppleWalletOptions.SecondaryFieldsEntry[]	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	AppleWalletOptions.AuxiliaryFieldsEntry[]	The auxiliary fields of the credential. This is a mapping between the order of an auxiliary field (0 or 1) and the field name.

AppleWalletOptions.AuxiliaryFieldsEntry¶

Field	Type	Description
key	int32
value	string

AppleWalletOptions.SecondaryFieldsEntry¶

Field	Type	Description
key	int32
value	string

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

DeleteCredentialTemplateRequest¶

Request to delete a template by ID

Field	Type	Description
id	string	ID of template to delete

DeleteCredentialTemplateResponse¶

Response to DeleteCredentialTemplateRequest

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

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 resuts via `ListCredentialTemplatesRequest`

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	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
context_uri	string	Deprecated. URI pointing to template JSON-LD context 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
annotations	TemplateField.AnnotationsEntry[]	Deprecated. Do not use. Annotations for the field that may be used to add additional information.
uri_data	UriFieldData	How to deal with this URI field when rendering credential. Only use if `type` is `URI`.

TemplateField.AnnotationsEntry¶

Field	Type	Description
key	string
value	string

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

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.

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.

Top

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

Service - VerifiableCredential¶

Method Name	Request Type	Response Type	Description
Issue	IssueRequest	IssueResponse	Sign and issue a verifiable credential from a submitted document. The document must be a valid JSON-LD document.
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

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

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
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
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`
framework_id	string	Governance framework ID to use with issuance of this credential. If specified, the issued credential will contain extended issuer metadata with membership info for the given ecosystem governance framework (EGF)
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.

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`

IssueRequest¶

Request to sign a JSON-LD Credential using public key tied to caller

Field	Type	Description
document_json	string	Valid JSON-LD Credential document to be signed, in string form

IssueResponse¶

Response to IssueRequest

Field	Type	Description
signed_document_json	string	Verifiable Credential document, signed with public key tied to caller of `IssueRequest`

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 send item to
wallet_id	string	Wallet ID of the recipient within the ecosystem
did_uri	string	DID URI of the recipient
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_messages	string[]	Deprecated. Use `validation_results` instead
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

Top

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

Service - TrustRegistry¶

Method Name	Request Type	Response Type	Description
AddFramework	AddFrameworkRequest	AddFrameworkResponse	Add a governance framework to the ecosystem
RemoveFramework	RemoveFrameworkRequest	RemoveFrameworkResponse	Remove a governance framework from the ecosystem
SearchRegistry	SearchRegistryRequest	SearchRegistryResponse	Search the ecosystem's governance frameworks
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
GetMembershipStatus	GetMembershipStatusRequest	GetMembershipStatusResponse	Fetch the membership status of an issuer for a given credential schema in a trust registry
FetchData	FetchDataRequest	FetchDataResponse stream	Not implemented.

AddFrameworkRequest¶

Request to register a new ecosystem governance framework in the current ecosystem

Field	Type	Description
governance_framework_uri	string	URI of governance framework organization
name	string	Name of governance framework organization
description	string	Description of governance framework

AddFrameworkResponse¶

Response to AddFrameworkRequest

Field	Type	Description
id	string	Unique framework identifier
governing_authority	string	DID URI of Trinsic account which created the governance framework
trust_registry	string	URN of trust registry for governance framework

FetchDataRequest¶

Not implemented.

Field	Type	Description
governance_framework_uri	string
query	string

FetchDataResponse¶

Not implemented.

Field	Type	Description
response_json	string
has_more_results	bool
continuation_token	string

GetMembershipStatusRequest¶

Request to fetch membership status in governance framework for a specific credential schema.

Field	Type	Description
framework_id	string	The ID of the ecosystem governance framework. This ID may be found in the 'trustRegistry' field in the verifiable credential model
did_uri	string	DID URI of member
schema_uri	string	URI of credential schema associated with membership

GetMembershipStatusResponse¶

Response to GetMembershipStatusRequest

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

GovernanceFramework¶

Ecosystem Governance Framework

Field	Type	Description
governance_framework_uri	string	URI of governance framework organization
trust_registry_uri	string	URI of trust registry associated with governance framework
description	string	Description of governance framework

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.
framework_id	string	ID of the governance framework that member is being added to

RegisterMemberResponse¶

Response to RegisterMemberRequest

RemoveFrameworkRequest¶

Request to remove a governance framework from the current ecosystem

Field	Type	Description
id	string	ID of governance framework to remove

RemoveFrameworkResponse¶

Response to RemoveFrameworkRequest

SearchRegistryRequest¶

Request to search all governance frameworks within ecosystem

Field	Type	Description
query	string	SQL query to execute against frameworks. Example: `SELECT c from c where c.type == 'GovernanceFramework'`
continuation_token	string	Token to fetch next set of results, from previous `SearchRegistryResponse`

SearchRegistryResponse¶

Response to SearchRegistryRequest

Field	Type	Description
items_json	string	JSON string containing array of resultant objects
has_more	bool	Whether more data is available to fetch for query
continuation_token	string	Token to fetch next set of results via `SearchRegistryRequest`

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.

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
framework_id	string	ID of the governance framework that member is being removed from

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

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/event/v1/event.proto¶

APICall¶

Field	Type	Description
source	string
request	bytes
response	bytes

GovernanceFrameworkCreatedV1¶

Entity Governance Framework created and attached to ecosystem

Field	Type	Description
id	string	UUID of the governance framework
ecosystem_id	string	UUID of the ecosystem that owns this EGF
trust_registry	string	Trust registry associated with this EGF
governing_authority	string	Wallet ID of the authority for this EGF
type	string	Type of EGF
name	string	User-friendly name for the EGF
description	string	Description of the EGF
governance_framework	string	URI for the EGF
timestamp	string	Timestamp event occurred, in ISO 8601 format (ex. `2022-07-07T08:09:10.11Z`)

ItemReceivedV1¶

Item inserted into wallet

Field	Type	Description
id	string	UUID of the new item
received	string	Timestamp when the item was received, in ISO 8601 format (ex. `2022-07-07T08:09:10.11Z`)
wallet_id	string	ID of wallet
ecosystem_id	string	Ecosystem where this event originated, if any.

PingV1¶

Webhook test event

Field	Type	Description
id	string	UUID of this ping
webhook_id	string	UUID of the webhook receiving the ping
timestamp	string	Timestamp ping was requested, in ISO 8601 format (ex. `2022-07-07T08:09:10.11Z`)
message	string	Arbitrary message specified when ping was requested
ecosystem_id	string	Ecosystem where this event originated, if any.

TemplateCreatedV1¶

Template created in ecosystem

Field	Type	Description
id	string	UUID of the template
ecosystem_id	string	UUID of the ecosystem that owns this template
name	string	Template name
type	string	Template type
created_by	string	WalletID that created the template
timestamp	string	Timestamp event occurred, in ISO 8601 format (ex. `2022-07-07T08:09:10.11Z`)

EventType¶

All event types

Name	Number	Description
PING	0
LOG	1
GOVERNANCE_FRAMEWORK_CREATED	5
GOVERNANCE_FRAMEWORK_MEMBER_REGISTERED	6
GOVERNANCE_FRAMEWORK_MEMBER_UNREGISTERED	7
TEMPLATE_CREATED	10
TEMPLATE_DELETED	11
WALLET_CREATED	15
ITEM_RECEIVED	16
CREDENTIAL_ISSUED	17

File-level Extensions¶

Extension	Type	Base	Number	Description
event_type	EventType	.google.protobuf.MessageOptions	60002	Event type associated with this Event message.

Top

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

Service - UniversalWallet¶

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

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.

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

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

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	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/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 resuts 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/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/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
UpdateEcosystem	UpdateEcosystemRequest	UpdateEcosystemResponse	Update an existing ecosystem
AddWebhook	AddWebhookRequest	AddWebhookResponse	Add a webhook endpoint to the ecosystem
DeleteWebhook	DeleteWebhookRequest	DeleteWebhookResponse	Delete a webhook endpoint from the ecosystem
EcosystemInfo	EcosystemInfoRequest	EcosystemInfoResponse	Get ecosystem information
GetPublicEcosystemInfo	GetPublicEcosystemInfoRequest	GetPublicEcosystemInfoResponse	Get public ecosystem information about any ecosystem
Invite	InviteRequest	InviteResponse	Invite a user to the ecosystem
InvitationStatus	InvitationStatusRequest	InvitationStatusResponse	Check the status of an invitation
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
RetrieveDomainVerificationRecord	RetrieveDomainVerificationRecordRequest	RetrieveDomainVerificationRecordResponse	Retrieve a random hash TXT that can be used to verify domain ownership
RefreshDomainVerificationStatus	RefreshDomainVerificationStatusRequest	RefreshDomainVerificationStatusResponse	Call to verify domain
SearchWalletConfigurations	SearchWalletConfigurationsRequest	SearchWalletConfigurationResponse	Search for issuers/providers/verifiers in the current ecosystem

AddWebhookRequest¶

Request to add a webhook to an ecosystem

Field	Type	Description
destination_url	string	Destination to post webhook calls to. Must be a reachable HTTPS URL.
secret	string	Secret string used for HMAC-SHA256 signing of webhook payloads to verify that a webhook comes from Trinsic
events	string[]	Events to subscribe to. Default is "*" (all events)

AddWebhookResponse¶

Response to AddWebhookRequest

Field	Type	Description
ecosystem	Ecosystem	Ecosystem data with new webhook

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
uri	string	Deprecated. External URL associated with your organization or ecosystem entity
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.

DeleteWebhookRequest¶

Request to delete a webhook from an ecosystem

Field	Type	Description
webhook_id	string	ID of webhook to delete

DeleteWebhookResponse¶

Response to DeleteWebhookRequest

Field	Type	Description
ecosystem	Ecosystem	Ecosystem data after removal of webhook

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
uri	string	Deprecated. External URL associated with the organization or ecosystem entity
display	EcosystemDisplay	Display details
domain	string	Domain

EcosystemDisplay¶

Field	Type	Description
light	EcosystemDisplayDetails	Removed the Dark after discussion with team, as we don't provide a dark UI anywhere (yet) in our platform. EcosystemDisplayDetails dark = 1;

EcosystemDisplayDetails¶

Field	Type	Description
logo_url	string
color	string

EcosystemDisplayDetailsRequest¶

Field	Type	Description
color	string
logo_data	bytes
logo_format	string	MIME type of the file

EcosystemDisplayRequest¶

Field	Type	Description
light	EcosystemDisplayDetailsRequest	Removed the Dark after discussion with team, as we don't provide a dark UI anywhere (yet) in our platform. EcosystemDisplayDetailsRequest dark = 1;

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

GetPublicEcosystemInfoRequest¶

Request to fetch information about an ecosystem

Field	Type	Description
ecosystem_id	string

GetPublicEcosystemInfoResponse¶

Response to InfoRequest

Field	Type	Description
ecosystem	PublicEcosystemInformation	Ecosystem corresponding to requested `ecosystem_id`

IndyOptions¶

Options for creation of DID on the SOV network

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

InvitationStatusRequest¶

Request details for the status of an invitation

Field	Type	Description
invitation_id	string	ID of invitation, received from `InviteResponse`

InvitationStatusResponse¶

Response to InvitationStatusRequest

Field	Type	Description
status	InvitationStatusResponse.Status	Status of invitation
status_details	string	Human-readable string with details about invitation status

InviteRequest¶

Request to invite a participant to an ecosystem

Field	Type	Description
participant	ParticipantType	Type of participant being invited (individual/organization)
description	string	Description of invitation
details	services.account.v1.AccountDetails	Account details of invitee

InviteRequest.DidCommInvitation¶

InviteResponse¶

Response to InviteRequest

Field	Type	Description
invitation_id	string	ID of created invitation
invitation_code	string	Invitation code -- must be passed back in `LoginRequest`

IonOptions¶

Options for creation of DID on the ION network

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

PublicEcosystemInformation¶

Field	Type	Description
name	string	Public name of this ecosystem
domain	string	Public domain for the owner of this ecosystem
domain_verified	bool	Trinsic verified the domain is owned by the owner of this ecosystem
style_display	EcosystemDisplay	Style display information
description	string	Description of the ecosystem

RefreshDomainVerificationStatusRequest¶

RefreshDomainVerificationStatusResponse¶

Field	Type	Description
domain	string	Domain URL verified
domain_verified	bool	Specifies if the above `domain` was successfully verified

RetrieveDomainVerificationRecordRequest¶

RetrieveDomainVerificationRecordResponse¶

Response message containing a TXT record content for domain url verification

Field	Type	Description
verification_record_name	string	TXT record name to use for domain verification
verification_record_Value	string	TXT code for domain verification

SearchWalletConfigurationResponse¶

Field	Type	Description
results	WalletConfiguration[]	Results matching the search query
has_more	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 _ WHERE [queryFilter]`
continuation_token	string	Token provided by previous `SearchResponse` if more data is available for query

UpdateEcosystemRequest¶

Request to update an ecosystem's metadata

Field	Type	Description
description	string	New description of the ecosystem
uri	string	Deprecated. New external URL associated with the organization or ecosystem entity
domain	string	New domain URL
display	EcosystemDisplayRequest	Deprecated. Display details

UpdateEcosystemResponse¶

Response to UpdateEcosystemRequest

Field	Type	Description
Ecosystem	Ecosystem	Current ecosystem metadata, post-update

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
email	string
sms	string
wallet_id	string
public_did	string
config_type	string

WebhookConfig¶

Webhook configured on an ecosystem

Field	Type	Description
id	string	UUID of the webhook
destination_url	string	HTTPS URL to POST webhook calls to
events	string[]	Events the webhook is subscribed to
status	string	Last known status of webhook (whether or not Trinsic can successfully reach destination)

IndyOptions.IndyNetwork¶

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

InvitationStatusResponse.Status¶

Name	Number	Description
Error	0	Onboarding resulted in error
InvitationSent	1	The participant has been invited
Completed	2	The participant has been onboarded
Expired	3	The invite has expired

IonOptions.IonNetwork¶

Name	Number	Description
TestNet	0
MainNet	1

ParticipantType¶

Type of participant being invited to ecosystem

Name	Number	Description
participant_type_individual	0	Participant is an individual
participant_type_organization	1	Participant is an organization

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

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