Skip to content

Account Service

The Account Service allows you to create and sign in to accounts.

Wallets vs Accounts

Wallets and accounts are related and often interchangeable -- each account has an associated wallet, and operations on a wallet are performed using an account's access token.

Every account has exactly one wallet.

Authentication Tokens

When you create or sign in to an account, the response is an authentication token string.

This string is an encoded form of your account profile, as well as an access key to perform calls using the account.

These are effectively API keys; they should be kept safe and never published.

Login

Attempts the first step of the login process for the specified account, creating it if it does not already exist.

Trinsic will response with a challenge, and send an authentication code to the account's email address.

The authentication code must be passed along with challenge to LoginConfirm to finalize the login.

trinsic account login --email "bob@example.com"

const loginResponse = await trinsic.account().login(
  LoginRequest.fromPartial({
    email: "bob@example.com",
  })
);

var loginResponse = await trinsic.Account.LoginAsync(new() {
    EcosystemId = ecosystemId,
    Email = "bob@example.com"
});

login_response = await trinsic.account.login(
    request=LoginRequest(email="bob@example.com")
)

loginResponse, err := trinsic.Account().Login(context.Background(), &account.LoginRequest{
    Email: "bob@example.com",
})

var loginResponse =
    trinsic
        .account()
        .login(LoginRequest.newBuilder().setEmail("bob@example.com").build())
        .get();

LoginRequest
Request to begin login flow
email
optional string
Email address of account. If unspecified, an anonymous account will be created.
invitation_code
optional string
Invitation code associated with this registration
ecosystem_id
optional string
ID of Ecosystem to sign into. Ignored if invitation_code is passed.

LoginResponse
Response to LoginRequest
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.
Show child attributes

Anonymous Login

Anonymous accounts are accounts which are not tied to any email or phone number, and do not require any authentication. They are typically used for testing and prototypes.

To create an anonymous account with an SDK, use the TrinsicService.LoginAnonymous() method.

To create an anonymous account with the CLI, simply leave the email parameter unspecified.

Login Confirm

Finalizes the login process.

You must pass challenge as it was received in response to Login, along with the confirmation code that was sent in an email.

Our SDK will take care of hashing the confirmation code for you.

trinsic account login --email "bob@example.com"

const authToken = await trinsic
  .account()
  .loginConfirm(loginResponse.challenge, "12345");

var authToken = await trinsic.Account.LoginConfirmAsync(loginResponse.Challenge, authCode);

auth_token = await trinsic.account.login_confirm(
    challenge=login_response.challenge, auth_code="12345"
)

authToken, err := trinsic.Account().LoginConfirm(context.Background(), loginResponse.GetChallenge(), "12345")

var authToken =
    trinsic.account().loginConfirm(loginResponse.getChallenge(), "12345").get();

LoginConfirmRequest
Request to finalize login flow
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
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.
Show child attributes

Get Account Info

Returns the account information (name, email address, phone number, etc.) used to create the currently-active account profile.

trinsic account info

const info = await accountService.info();

var info = await trinsic.Account.GetInfoAsync();

info = await service.get_info()

info2, err2 := trinsic.Account().GetInfo(context.Background())

var info = trinsic.account().getInfo().get();

AccountInfoRequest
Request for information about the account used to make the request
This message has no fields

AccountInfoResponse
Information about the account used to make the request
details
AccountDetails
The account details associated with the calling request context
Show child attributes
ecosystems
AccountEcosystem[]
Use ecosystem_id instead
Show child attributes
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
authorized_webhooks
string[]
Webhook events, if any, this wallet has authorized

Note

This call returns the information associated with the authentication token used to create the request; therefore, it is not possible to pass a different authentication token to this call. Otherwise, Trinsic's zero-knowledge proof authentication scheme would be violated.

When using the CLI, this will return information for the account most recently logged in to.

When using the SDK, this will return information for the authentication token stored in the AccountService instance's ServiceOptions.AuthToken field, which will be the account most recently logged in to, unless you have manually set this value yourself.

Authorize Webhook

Authorizes the ecosystem provider to receive webhooks pertaining to this wallet.

trinsic account authorize-webhook --events "*"

const response = await trinsic.account().authorizeWebhook(
  AuthorizeWebhookRequest.fromPartial({
    events: ["*"], // Authorize all events
  })
);

var request = new AuthorizeWebhookRequest();
request.Events.Add("*"); //Authorize all events

await trinsic.Account.AuthorizeWebhookAsync(request);

request = AuthorizeWebhookRequest()
request.events.append("*")
response = await trinsic.account.authorize_webhook(request=request)

request := &account.AuthorizeWebhookRequest{
    Events: []string{"*"}, //Authorize all events
}

authResponse, err := trinsic.Account().AuthorizeWebhook(context.Background(), request)

var authorizeResponse =
    trinsic
        .account()
        .authorizeWebhook(
            AuthorizeWebhookRequest.newBuilder()
                .addEvents("*") // Authorize all events
                .build())
        .get();

AuthorizeWebhookRequest
Request to authorize Ecosystem provider to receive webhooks for events which occur on this wallet.
events
string[]
Events to authorize access to. Default is "*" (all events)

AuthorizeWebhookResponse
Response to AuthorizeWebhookRequest
This message has no fields

Protect Account Profile

Deprecated Sign-in Flow

This section is related to the the deprecated SignIn endpoint; the new Login flow does not require the use of Protect and Unprotect.

Protects the specified account profile with a security code. It is not possible to execute this call using the CLI.

const protectedProfile = await accountService.protect(accountProfile, "1234");

var securityCode = "1234";
var myProtectedProfile = AccountService.Protect(myProfile, securityCode);
var myUnprotectedProfile = AccountService.Unprotect(myProtectedProfile, securityCode);

code = b"1234"
my_protected_profile = account_service.protect(
    profile=my_profile, security_code=code
)
my_unprotected_profile = account_service.unprotect(
    profile=my_protected_profile, security_code=code
)

securityCode := "1234"
protectedProfile, err := trinsic.Account().Protect(profile, securityCode)
if !assert2.Nil(err) {
    return
}
unprotectedProfile, err := trinsic.Account().Unprotect(protectedProfile, securityCode)
if !assert2.Nil(err) {
    return
}

var code = "1234";
var myProtectedProfile = AccountService.protect(myProfile, code);
var myUnprotectedProfile = AccountService.unprotect(myProtectedProfile, code);

Info

In this context, "protection" refers to a cryptographic operation on the authorization token for an account.

Protecting an account profile with code c returns a new access token which is unusable until it is unprotected with the same code c. It is not possible to reverse the protection process without the original protection code.

You will receive a protected account profile from Trinsic if you attempt to sign in to an account via email, SMS, or any other method which requires authentication. Trinsic will send a security code to the email or phone number associated with the account, which can be used to unprotect the account profile.

Specifically, Trinsic is using Oberon to handle access tokens; protection and unprotection is handled using the blinding/unblinding features of Oberon.

Unprotect Account Profile

Deprecated Sign-in Flow

This section is related to the the deprecated SignIn endpoint; the new Login flow does not require the use of Protect and Unprotect.

Unprotects the specified account profile using the given code. It is not possible to execute this call using the CLI.

The profile must have been previously protected using the same code that is being used to unprotect it. Profiles can be protected using any arbitrary code via the Protect method.

Most commonly, this method is used on a protected profile received from the Sign In method. The code to unprotect it will have been sent to the account owner via email or SMS.

const accountProfile = await accountService.unprotect(protectedProfile, "1234");

var securityCode = "1234";
var myProtectedProfile = AccountService.Protect(myProfile, securityCode);
var myUnprotectedProfile = AccountService.Unprotect(myProtectedProfile, securityCode);

code = b"1234"
my_protected_profile = account_service.protect(
    profile=my_profile, security_code=code
)
my_unprotected_profile = account_service.unprotect(
    profile=my_protected_profile, security_code=code
)

securityCode := "1234"
protectedProfile, err := trinsic.Account().Protect(profile, securityCode)
if !assert2.Nil(err) {
    return
}
unprotectedProfile, err := trinsic.Account().Unprotect(protectedProfile, securityCode)
if !assert2.Nil(err) {
    return
}

var code = "1234";
var myProtectedProfile = AccountService.protect(myProfile, code);
var myUnprotectedProfile = AccountService.unprotect(myProtectedProfile, code);

[Deprecated] Sign In

Deprecated

This endpoint is deprecated, and will be removed in the near future.

Please use Login and LoginConfirm.

Sign in to an existing account, or create a new one.

If no account details are passed to this method, an anonymous account will be created.

trinsic account login --email <PROFILE_EMAIL> --name <PROFILE_NAME>

const allison = (await accountService.signIn()).getProfile();

var myProfile = await trinsic.Account.SignInAsync(new());

my_profile = await account_service.login_anonymous()

profile, err := trinsic.Account().LoginAnonymous(context.Background())
if !assert2.Nil(err) {
    return
}

var myProfile = trinsic.account().signIn().get();

SignInRequest
Request for creating or signing into an account
details
optional AccountDetails
Account registration details
Show child attributes
invitation_code
optional string
Invitation code associated with this registration
ecosystem_id
optional 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.
confirmation_method
ConfirmationMethod
Indicates if confirmation of account is required.
Show enum values
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.
Show child attributes

This operation, if successful, returns an authentication token string.

Protected Authentication Tokens

If you are attempting to login to a non-anonymous account (by specifying an email address or phone number), the authentication token returned will be protected, and cannot be used until it has been unprotected.

Trinsic will have sent a security code to the account's email address or phone number; this security code must be used with the Unprotect call to receive a usable authentication token.

In the future, we will provide an SDK call to determine if an authentication token is protected.