Skip to content

Protocol Documentation

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

Top

sdk/options/v1/options.proto

TrinsicOptions

Configuration for Trinsic SDK Services

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

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

Top

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

Service - FileManagement

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

DeleteFileRequest

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

Field Type Description
id string ID of file to delete

DeleteFileResponse

Response to DeleteFileRequest. Empty payload.

File

Contains information about a file stored in Trinsic's CDN

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

GetFileRequest

Request to fetch information about a stored file

Field Type Description
id string ID of file to fetch

GetFileResponse

Response to GetFileRequest

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

GetStorageStatsRequest

Request to get statistics about files uploaded by this account

GetStorageStatsResponse

Response to GetStorageStatsRequest

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

ListFilesRequest

Request to list files

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

ListFilesResponse

Response to ListFilesRequest

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

StorageStats

Represents aggregate statistics of all files uploaded by a single issuer

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

UploadFileRequest

Request to upload a file to Trinsic's CDN

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

UploadFileResponse

Response to UploadFileRequest

Field Type Description
uploaded_file File Information about newly-uploaded file

Top

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

AccountDetails

Account registration details

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

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
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
auth_tokens WalletAuthToken[] List of active authentication tokens for this wallet. This list does not contain the issued token, only metadata such as ID, description, and creation date.

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.

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.
ecosystem_id string ID of Ecosystem to sign into.

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

WalletAuthToken

Information about authentication tokens for a wallet

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

ConfirmationMethod

Confirmation method type for two-factor workflows

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

Top

services/options/field-options.proto

AnnotationOption

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

SdkTemplateOption

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

File-level Extensions

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

Top

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

Service - VerifiableCredential

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

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
save_copy bool Save a copy of the issued credential to this user's wallet. This copy will only contain the credential data, but not the secret proof value. Issuers may use this data to keep track of the details for revocation status.
expiration_date string The ISO8601 expiration UTC date of the credential. This is a reserved field in the VC specification. If specified, the issued credential will contain an expiration date. https://www.w3.org/TR/vc-data-model/#expiration
include_governance bool If true, the issued credential will contain an attestation of the issuer's membership in the ecosystem's governance framework.

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

RevealTemplateAttributes

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

SendRequest

Request to send a document to another user's wallet

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

SendResponse

Response to SendRequest

UpdateStatusRequest

Request to update a credential's revocation status

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

UpdateStatusResponse

Response to UpdateStatusRequest

ValidationMessage

Result of a validation check on a proof

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

VerifyProofRequest

Request to verify a proof

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

VerifyProofResponse

Response to VerifyProofRequest

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

VerifyProofResponse.ValidationResultsEntry

Field Type Description
key string
value ValidationMessage

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

CreateCredentialTemplateRequest

Request to create a new template

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

CreateCredentialTemplateRequest.FieldOrderingEntry

Field Type Description
key string
value FieldOrdering

CreateCredentialTemplateRequest.FieldsEntry

Field Type Description
key string
value TemplateField

CreateCredentialTemplateResponse

Response to CreateCredentialTemplateRequest

Field Type Description
data TemplateData Created template

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_results bool Whether more results are available for this query via continuation_token
continuation_token string Token to fetch next set of results via SearchCredentialTemplatesRequest

TemplateData

Credential Template

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

TemplateData.FieldOrderingEntry

Field Type Description
key string
value FieldOrdering

TemplateData.FieldsEntry

Field Type Description
key string
value TemplateField

TemplateField

A field defined in a template

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

TemplateFieldPatch

A patch to apply to an existing template field

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

UpdateCredentialTemplateRequest

Request to update display information for a template

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

UpdateCredentialTemplateRequest.FieldOrderingEntry

Field Type Description
key string
value FieldOrdering

UpdateCredentialTemplateRequest.FieldsEntry

Field Type Description
key string
value TemplateFieldPatch

UpdateCredentialTemplateResponse

Response to UpdateCredentialTemplateRequest

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

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

Service - Provider

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

CreateEcosystemRequest

Request to create an ecosystem

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

CreateEcosystemResponse

Response to CreateEcosystemRequest

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

Ecosystem

Details of an ecosystem

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

EcosystemInfoRequest

Request to fetch information about an ecosystem

EcosystemInfoResponse

Response to InfoRequest

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

GetOberonKeyRequest

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

GetOberonKeyResponse

Response to GetOberonKeyRequest

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

IndyOptions

Options for creation of DID on the SOV network

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

IonOptions

Options for creation of DID on the ION network

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

RefreshDomainVerificationStatusRequest

The below display can be removed only once the Dashboard is updating this itself - currently it uses this request DEPRECATED, will be removed June 1st 2023

RefreshDomainVerificationStatusResponse

The below display can be removed only once the Dashboard is updating this itself - currently it uses this request DEPRECATED, will be removed June 1st 2023

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

RetrieveDomainVerificationRecordRequest

The below display can be removed only once the Dashboard is updating this itself - currently it uses this request DEPRECATED, will be removed June 1st 2023

RetrieveDomainVerificationRecordResponse

The below display can be removed only once the Dashboard is updating this itself - currently it uses this request DEPRECATED, will be removed June 1st 2023

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_results bool Whether more results are available for this query via continuation_token
continuation_token string Token to fetch next set of results via SearchRequest

SearchWalletConfigurationsRequest

Search for issuers/holders/verifiers

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

UpgradeDidRequest

Request to upgrade a wallet

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

UpgradeDidResponse

Response to UpgradeDIDRequest

Field Type Description
did string New DID of wallet

WalletConfiguration

Strongly typed information about wallet configurations

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

WalletExternalIdentity

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

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

IdentityProvider

Name Number Description
Unknown 0 Identity provider is unknown
Email 1 Identity provider is email
Phone 2 Identity provider is phone

IndyOptions.IndyNetwork

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

IonOptions.IonNetwork

Name Number Description
TestNet 0
MainNet 1

Top

services/provider/v1/access-management.proto

Service - AccessManagement

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

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

AddRoleAssignmentRequest

Role management

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

AddRoleAssignmentResponse

ListAvailableRolesRequest

Request to fetch the available roles in the current ecosystem

ListAvailableRolesResponse

Field Type Description
roles string[] List of roles

ListRoleAssignmentsRequest

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

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

ListRoleAssignmentsResponse

Field Type Description
roles string[] List of roles

RemoveRoleAssignmentRequest

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

RemoveRoleAssignmentResponse

Top

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

Service - UniversalWallet

Service for managing wallets

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

AddExternalIdentityConfirmRequest

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

AddExternalIdentityConfirmResponse

AddExternalIdentityInitRequest

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

AddExternalIdentityInitResponse

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

AuthenticateConfirmRequest

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

AuthenticateConfirmResponse

Field Type Description
auth_token string Auth token for the wallet

AuthenticateInitRequest

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

AuthenticateInitResponse

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

AuthenticateResendCodeRequest

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

AuthenticateResendCodeResponse

CreateWalletRequest

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

CreateWalletRequest.ExternalIdentity

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

CreateWalletResponse

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

DeleteItemRequest

Request to delete an item in a wallet

Field Type Description
item_id string ID of item to delete

DeleteItemResponse

Response to DeleteItemRequest

DeleteWalletRequest

Request to delete a wallet

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

DeleteWalletResponse

Response to DeleteWalletRequest. Empty payload.

GenerateAuthTokenRequest

Field Type Description
wallet_id string
token_description string

GenerateAuthTokenResponse

Field Type Description
token_id string
auth_token string

GetItemRequest

Request to fetch an item from wallet

Field Type Description
item_id string ID of item in wallet

GetItemResponse

Response to GetItemRequest

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

GetMyInfoRequest

Request to retrieve wallet information about the currently authenticated wallet

GetMyInfoResponse

Response to GetMyInfoRequest

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

GetWalletInfoRequest

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

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

GetWalletInfoResponse

Response to GetWalletInfoRequest

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

InsertItemRequest

Request to insert a JSON document into a wallet

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

InsertItemResponse

Response to InsertItemRequest

Field Type Description
item_id string ID of item inserted into wallet

ListWalletsRequest

Field Type Description
filter string

ListWalletsResponse

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

RemoveExternalIdentityRequest

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

RemoveExternalIdentityResponse

RevokeAuthTokenRequest

Request to revoke a previously issued auth token

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

RevokeAuthTokenResponse

SearchRequest

Request to search items in wallet

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

SearchResponse

Response to SearchRequest

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

UpdateItemRequest

Request to update item in wallet

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

UpdateItemResponse

Response to UpdateItemRequest

Top

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

Service - TrustRegistry

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

AuthorizedMember

Field Type Description
did string
authorized_member_schemas AuthorizedMemberSchema[]

AuthorizedMemberSchema

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

GetMemberAuthorizationStatusRequest

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

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

GetMemberAuthorizationStatusResponse

Response to GetMemberAuthorizationStatusRequest

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

GetMemberRequest

Request to get a member of the governance framework

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

GetMemberResponse

Response to GetMemberAuthorizationStatusRequest

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

ListAuthorizedMembersRequest

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

ListAuthorizedMembersResponse

Response to ListAuthorizedMembersRequest

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

RegisterMemberRequest

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

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

RegisterMemberResponse

Response to RegisterMemberRequest

UnregisterMemberRequest

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

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

UnregisterMemberResponse

Response to UnregisterMemberRequest

RegistrationStatus

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

Top

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

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