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	string	Default ecosystem ID to use for various SDK calls; defaults to `default`

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

AccountDetails¶

Account registration details

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

AccountEcosystem¶

Field	Type	Description
id	string
name	string
description	string
uri	string

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.

InfoRequest¶

Request for information about the account used to make the request

InfoResponse¶

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 "issuer" when signing verifiable credentials

ListDevicesRequest¶

ListDevicesResponse¶

RevokeDeviceRequest¶

RevokeDeviceResponse¶

SignInRequest¶

Request for creating or signing into an account

Field	Type	Description
details	AccountDetails	Account registration details
invitation_code	string	Invitation code associated with this registration
ecosystem_id	string	ID of Ecosystem to sign into. 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. This settings is configured globally by the server administrator.
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	Indicates third-party method of confirmation is required

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

ServerConfig¶

Field	Type	Description
endpoint	string	service endpoint
port	int32	service port
use_tls	bool	indicates if tls is used

ResponseStatus¶

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

Top

services/debug/v1/debug.proto¶

Service - Debugging¶

Method Name	Request Type	Response Type	Description
CallEmpty	.google.protobuf.Empty	.google.protobuf.Empty
CallEmptyAuth	.google.protobuf.Empty	.google.protobuf.Empty

Top

services/options/field-options.proto¶

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.

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
GenerateToken	GenerateTokenRequest	GenerateTokenResponse	Generates an unprotected authentication token that can be used to configure server side applications
Invite	InviteRequest	InviteResponse	Invite a user to the ecosystem
InvitationStatus	InvitationStatusRequest	InvitationStatusResponse	Check the invitation status
GetOberonKey	GetOberonKeyRequest	GetOberonKeyResponse	Returns the public key being used to create/verify oberon tokens

CreateEcosystemRequest¶

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.
description	string	Ecosystem description
uri	string	External URL associated with your organization or ecosystem entity
details	services.account.v1.AccountDetails	The account details of the owner of the ecosystem

CreateEcosystemResponse¶

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. This setting is configured globally by the server administrator.

Ecosystem¶

Field	Type	Description
id	string
name	string
description	string
uri	string

GenerateTokenRequest¶

Field	Type	Description
description	string	Description to identify this token

GenerateTokenResponse¶

Field	Type	Description
profile	services.account.v1.AccountProfile	Account authentication profile that contains unprotected token

GetOberonKeyRequest¶

request message for GetOberonKey

GetOberonKeyResponse¶

response message for GetOberonKey

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

InvitationStatusRequest¶

Request details for the status of onboarding an individual or organization. The reference_id passed is the response from the Onboard method call

Field	Type	Description
invitation_id	string	ID of invitation

InvitationStatusResponse¶

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

Invite¶

Field	Type	Description
id	string
code	string
created	string
accepted	string
expires	string

InviteRequest¶

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¶

Field	Type	Description
invitation_id	string	ID of created invitation
invitation_code	string	Invitation Code that must be passed with the account 'SignIn' request to correlate this user with the invitation sent.

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

ParticipantType¶

Name	Number	Description
participant_type_individual	0
participant_type_organization	1

Top

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

Service - TrustRegistry¶

Method Name	Request Type	Response Type	Description
AddFramework	AddFrameworkRequest	AddFrameworkResponse	Adds a trust registry defintion to the ecosystem
RemoveFramework	RemoveFrameworkRequest	RemoveFrameworkResponse
SearchRegistry	SearchRegistryRequest	SearchRegistryResponse
RegisterMember	RegisterMemberRequest	RegisterMemberResponse	Registers an authoritative issuer with a credential template
UnregisterMember	UnregisterMemberRequest	UnregisterMemberResponse	Removes an authoritative issuer with a credential template from the trust registry
GetMembershipStatus	GetMembershipStatusRequest	GetMembershipStatusResponse
FetchData	FetchDataRequest	FetchDataResponse stream

AddFrameworkRequest¶

Register new ecosystem governance framework

Field	Type	Description
governance_framework_uri	string
name	string
description	string

AddFrameworkResponse¶

Field	Type	Description
id	string	Unique framework identifier
governing_authority	string
trust_registry	string

FetchDataRequest¶

Field	Type	Description
governance_framework_uri	string
query	string

FetchDataResponse¶

Field	Type	Description
response_json	string
has_more_results	bool
continuation_token	string

GetMembershipStatusRequest¶

Field	Type	Description
governance_framework_uri	string
did_uri	string
x509_cert	string
schema_uri	string

GetMembershipStatusResponse¶

Field	Type	Description
status	RegistrationStatus

GovernanceFramework¶

Field	Type	Description
governance_framework_uri	string
trust_registry_uri	string
description	string

RegisterMemberRequest¶

Field	Type	Description
did_uri	string
wallet_id	string
email	string
schema_uri	string
valid_from_utc	uint64
valid_until_utc	uint64
framework_id	string	the id of the governance framework

RegisterMemberResponse¶

RemoveFrameworkRequest¶

Field	Type	Description
id	string

RemoveFrameworkResponse¶

SearchRegistryRequest¶

Field	Type	Description
query	string	SELECT c from c where c.type == 'GovernanceFramework'
continuation_token	string

SearchRegistryResponse¶

Field	Type	Description
items_json	string
has_more	bool
continuation_token	string

UnregisterMemberRequest¶

Field	Type	Description
did_uri	string
wallet_id	string
email	string
schema_uri	string
framework_id	string

UnregisterMemberResponse¶

RegistrationStatus¶

Name	Number	Description
CURRENT	0	- the entity is currently authorized, as of time of the query.
EXPIRED	1	- entity rights have expired.
TERMINATED	2	- entity has voluntarily ceased Issuer role under the specific EGF.
REVOKED	3	- entity authority under specific EGF was terminated by the governing authority.
NOT_FOUND	10

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

DeleteItemRequest¶

Request to delete an item in a wallet

Field	Type	Description
item_id	string	ID of item to delete

DeleteItemResponse¶

Response to DeleteItemRequest

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/verifiable-credentials/templates/v1/templates.proto¶

Service - CredentialTemplates¶

Method Name	Request Type	Response Type
Create	CreateCredentialTemplateRequest	CreateCredentialTemplateResponse
Get	GetCredentialTemplateRequest	GetCredentialTemplateResponse
List	ListCredentialTemplatesRequest	ListCredentialTemplatesResponse
Search	SearchCredentialTemplatesRequest	SearchCredentialTemplatesResponse
Delete	DeleteCredentialTemplateRequest	DeleteCredentialTemplateResponse

CreateCredentialTemplateRequest¶

Request to create a new template

Field	Type	Description
name	string	Name of new template
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`

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

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

GetTemplateRequest¶

Unused

Field	Type	Description
id	string

GetTemplateResponse¶

Unused

Field	Type	Description
data	TemplateData

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`

ListTemplatesRequest¶

Unused

ListTemplatesResponse¶

Unused

Field	Type	Description
templates	TemplateData[]

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	Count of items in `items_json` int32 count = 3; unpopulated and unused 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	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

TemplateData.FieldsEntry¶

Field	Type	Description
key	string
value	TemplateField

TemplateField¶

A field defined in a template

Field	Type	Description
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

FieldType¶

Valid types for credential fields

Name	Number	Description
STRING	0
NUMBER	1
BOOL	2
DATETIME	4

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 entry in 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

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

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)

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`

SendRequest¶

Request to send a document to another user's wallet

Field	Type	Description
email	string	Email address of user to send item to
did_uri	string	DID of recipient (presently unsupported)
didcomm_invitation_json	string	DIDComm out-of-band invitation JSON (presently unsupported)
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
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 or not 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 or not 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

Scalar Value Types¶

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)

Authors: Scott Phillips, Joshua Coffey