Protocol Documentation
This page documents the Protobuf Services and Messages which compose the Trinsic API.
Top
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
rpc SIgnInConfirm (SignInConfirmRequest) returns (SignInConfirmResponse); |
| Info | InfoRequest | InfoResponse | Get account information |
| ListDevices | ListDevicesRequest | ListDevicesResponse | List all connected devices |
| RevokeDevice | RevokeDeviceRequest | RevokeDeviceResponse | Revoke device access to the account's cloud wallet |
AccountDetails
Account registration details
Field
Type
Description
name
string
Account name
email
string
Email account
sms
string
SMS number including country code
AccountEcosystem
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
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
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
Ecosystem
GenerateTokenRequest
Field
Type
Description
description
string
Description to identify this token
GenerateTokenResponse
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
Invite
InviteRequest
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
AddFrameworkRequest
Register new ecosystem governance framework
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
GetMembershipStatusResponse
GovernanceFramework
Field
Type
Description
governance_framework_uri
string
trust_registry_uri
string
description
string
RegisterMemberRequest
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
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
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
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
CreateCredentialTemplateResponse
Response to CreateCredentialTemplateRequest
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
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
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
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
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
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)