package org.signal.chat.account
Get desktop application:
View/edit binary Protocol Buffers messages
service Accounts
account.proto:16Provides methods for working with Signal accounts.
rpc ChangeNumber (, )
account.proto:73Changes the phone number associated with the authenticated account.
message
account.proto:378oneof verification
A means of authenticating the change-number request for the new phone number. Exactly one must be provided.
bytes session_id = 1
A verified registration session ID (as returned by the registration service) for the new phone number.
bytes recovery_password = 2
A registration recovery password for the new phone number.
string number = 3
The new phone number for the authenticated account.
bytes registration_lock = 4
The registration lock secret for the new phone number, if the account associated with the new phone number has a registration lock configured.
bytes pni_identity_key = 5
The new public identity key to use for the phone-number identity (PNI) associated with the new phone number.
optional device_messages = 6
Synchronization messages to send to companion devices to supply the private keys associated with the new identity key and their new pre-keys. Exactly one message must be supplied for each device other than the sending (primary) device. May be omitted if no companion devices are linked to the account.
map<uint32, > device_pni_signed_pre_keys = 7
A new signed EC pre-key for each device on the account, including the sending device, keyed by device ID. Each must be accompanied by a valid signature from the identity key in this request.
map<uint32, > device_pni_pq_last_resort_pre_keys = 8
A new signed post-quantum last-resort pre-key for each device on the account, including the sending device, keyed by device ID. Each must be accompanied by a valid signature from the identity key in this request.
map<uint32, uint32> pni_registration_ids = 9
The new phone-number-identity registration ID for each device on the account, including the sending device, keyed by device ID.
message
account.proto:423oneof response
account_identifiers = 1
The identifiers of the account after the successful number change.
mismatched_devices = 2
Mismatched number of devices or device ids in 'devices to notify' list
registration_lock_failure = 3
The account associated with the new phone number has a registration lock, and the provided registration lock secret was missing or incorrect.
stale_devices = 4
Mismatched registration ids in 'devices to notify' list
message_too_large = 5
One or more device messages was too large
unverified_registration_session = 6
The registration session is unverified
invalid_registration_session = 7
The number does not match the registration session, or the registration session is invalid
recovery_password_verification_failed = 8
Removes any registration lock credentials from the authenticated account.
message
account.proto:192(message has no fields)
message
account.proto:195(message has no fields)
Configures "unidentified access" keys and preferences for the authenticated account. Other users permitted to interact with this account anonymously may take actions like fetching pre-keys and profiles for this account or sending sealed-sender messages without providing identifying credentials.
message
account.proto:284oneof configuration
bytes unidentified_access_key = 1
The key that other users must provide to interact with this account anonymously (i.e. to retrieve keys or profiles or to send messages) unless unrestricted unidentified access is permitted. Must be present if unrestricted unidentified access is not allowed.
allow_unrestricted_unidentified_access = 2
If set, any user may interact with this account anonymously without providing an unidentified access key. Otherwise, users must provide the given unidentified access key to interact with this account anonymously. Setting unrestricted unidentified access will clear any existing unidentified_access_key
message
account.proto:301(message has no fields)
rpc ConfirmTotpKey (, )
account.proto:92Confirms that the caller has stored and can derive one-time passwords from a pending TOTP key generated via `GenerateTotpKey` and stores/activates the key for the caller's account TOTP keys may only be generated for accounts without phone numbers.
message
account.proto:563uint32 one_time_password = 1
A one-time password derived from the current pending TOTP key
bytes metadata_ciphertext = 2
The ciphertext of user-provided metadata (presumably including a human-readable name and creation timestamp) to be attached to the newly-confirmed key
message
account.proto:573oneof response
key_confirmed = 1
The provided one-time password was accepted and the pending TOTP key was stored with the provided name ciphertext
one_time_password_not_verified = 2
The provided one-time password was not valid for any reason (including incorrect passwords, misaligned clocks, or missing account records)
too_many_mfa_keys = 3
The authenticated account already has too many MFA keys of all types, and the caller must remove one before adding more
rpc ConfirmUsernameHash (, )
account.proto:42Sets the username hash/encrypted username to a previously-reserved value (see `ReserveUsernameHash`).
message
account.proto:216bytes username_hash = 1
The username hash to claim for the authenticated account.
bytes zk_proof = 2
A zero-knowledge proof that the given username hash was generated by the Signal username algorithm.
bytes username_ciphertext = 3
The ciphertext of the chosen username for use in public-facing contexts (e.g. links and QR codes).
message
account.proto:229oneof response
confirmed_username_hash = 1
The details of the successfully confirmed username.
reservation_not_found = 2
The provided hash was not reserved for the account.
username_not_available = 3
The reservation has lapsed and the requested username has been claimed by another caller.
rpc DeleteAccount (, )
account.proto:27Deletes the authenticated account, purging all associated data in the process.
message
account.proto:178(message has no fields)
message
account.proto:181(message has no fields)
rpc DeleteUsernameHash (, )
account.proto:46Clears the current username hash, ciphertext, and link for the authenticated user.
message
account.proto:250(message has no fields)
message
account.proto:253(message has no fields)
rpc DeleteUsernameLink (, )
account.proto:54Clears any username link associated with the authenticated account.
message
account.proto:278(message has no fields)
message
account.proto:281(message has no fields)
Attemps to verify an MFA factor associated with this account.
message
account.proto:730oneof credential
uint32 totp_password = 1
/ A 6-digit TOTP password to validate
string webauthn_authentication_response_json = 2
/ A WebAuthn-compatible JSON-serialized authentication response
message
account.proto:740bool success = 1
/ If true, the selected authentication factor was verified correctly.
Concludes a WebAuthn registration ceremony to add a passkey to the authenticated account WebAuthn credentials may only be registered for accounts without phone numbers
message
account.proto:622bytes attestation_object = 1
The attestation object from a completed registration ceremony, serialized as specified in https://www.w3.org/TR/webauthn/#attestation-object
string collected_client_data_json = 2
The "collected client data" map used in the registration ceremony, as the exact JSON map that was hashed for the authenticator
bytes metadata_ciphertext = 3
The ciphertext of user-provided metadata (presumably including a human-readable name and creation timestamp) to be attached to the newly-confirmed key
message
account.proto:637oneof response
key_confirmed = 1
The provided public key has been registered for the account
key_not_confirmed = 2
The registration response was not verified successfully for any reason
too_many_mfa_keys = 3
The authenticated account already has too many MFA keys, and the caller must remove one before adding one (this can be true even if it was not when starting the request, since there is nothing to prevent multiple registrations from occurring in parallel)
rpc GenerateTotpKey (, )
account.proto:85Generates and stores a pending TOTP key for the authenticated account. To "activate" the key, callers must call the `ConfirmTotpKey` endpoint. TOTP keys may only be generated for accounts without phone numbers.
message
account.proto:536(message has no fields)
message
account.proto:539oneof response
key_generated = 1
A new, pending TOTP key has been generated and added to the authenticated account
too_many_totp_keys = 2
The authenticated account already has too many TOTP keys, and the caller must remove one before adding more
too_many_mfa_keys = 3
The authenticated account already has too many MFA keys of all types, and the caller must remove one before adding more
rpc GetAccountDataReport (, )
account.proto:76Produces a report of non-ephemeral account data stored by the service
message
account.proto:479(message has no fields)
message
account.proto:482string json = 3
The JSON representation of the data report
string text = 4
A plaintext representation of the data report
rpc GetAccountIdentity (, )
account.proto:20Returns basic identifiers for the authenticated account.
message
account.proto:141(message has no fields)
message
account.proto:144optional account_identifiers = 1
The identifiers for the authenticated account.
rpc GetCapabilities (, )
account.proto:79Gets the capabilities for the authenticated account.
message
account.proto:489(message has no fields)
message
account.proto:497optional capabilities = 1
A list of capabilities enabled on the account.
rpc GetEntitlements (, )
account.proto:23Returns entitlements for the authenticated account.
message
account.proto:149(message has no fields)
message
account.proto:152repeated badges = 1
Active badges added via Donations.redeemReceipt
optional backup = 2
If present, the backup level set via Backups.redeemReceipt
rpc ListMfaKeys (, )
account.proto:105Returns a list of confirmed MFA keys for the authenticated account
message
account.proto:658(message has no fields)
message
account.proto:660map<uint32, > keys = 1
rpc RemoveMfaKey (, )
account.proto:112Removes an MFA key from the authenticated account
message
account.proto:700uint32 key_id = 1
The account-specific identifier of the MFA key to remove
message
account.proto:705(message has no fields)
rpc ReserveUsernameHash (, )
account.proto:38Attempts to reserve one of multiple given username hashes. Reserved usernames may be claimed later via `ConfirmUsernameHash`.
message
account.proto:198repeated bytes username_hashes = 1
A prioritized list of username hashes to attempt to reserve.
message
account.proto:205oneof response
bytes username_hash = 1
The first username hash that was available (and actually reserved).
username_not_available = 2
Indicates that, of all of the candidate hashes provided, none were available. Callers may generate a new set of hashes and and retry.
Sets whether the authenticated account may be discovered by phone number via the Contact Discovery Service (CDS).
message
account.proto:304bool discoverable_by_phone_number = 1
If true, the authenticated account may be discovered by phone number via the Contact Discovery Service (CDS). Otherwise, other users must discover this account by other means (i.e. by username).
message
account.proto:311(message has no fields)
rpc SetMfaKeyMetadata (, )
account.proto:109Updates encrypted, user-supplied metadata (e.g. a human-readable name and creation timestamp) for an existing, confirmed MFA key
message
account.proto:678uint32 key_id = 1
The account-specific identifier of the MFA key to modify
bytes metadata_ciphertext = 2
The ciphertext of the new user-provided metadata to be attached to the identified key
message
account.proto:687oneof response
success = 1
New metadata was stored for the identified key
key_not_found = 2
No TOTP was found with the given ID
rpc SetRegistrationLock (, )
account.proto:31Sets the registration lock secret for the authenticated account. To remove a registration lock, please use `ClearRegistrationLock`.
message
account.proto:184bytes registration_lock = 1
The new registration lock secret for the authenticated account.
message
account.proto:189(message has no fields)
Sets the registration recovery password for the authenticated account.
message
account.proto:314bytes registration_recovery_password = 1
The new registration recovery password for the authenticated account.
message
account.proto:319(message has no fields)
rpc SetUsernameLink (, )
account.proto:51Associates the given username ciphertext with the account, replacing any previously stored ciphertext. A new link handle will optionally be created, and the link handle to use will be returned in any event.
message
account.proto:256bytes username_ciphertext = 1
The username ciphertext for which to generate a new link handle.
bool keep_link_handle = 2
If true and the account already had an encrypted username stored, the existing link handle will be reused. Otherwise a new link handle will be created.
message
account.proto:267oneof response
bytes username_link_handle = 1
A new link handle for the given username ciphertext.
no_username_set = 2
The authenticated account did not have a username set.
rpc SetZkCredentialKey (, )
account.proto:70Store a public key used to issue and verify zero-knowledge (anonymous) credentials for the account.
message
account.proto:365bytes public_key = 1
A serialized libsignal ZkCredentialPublicKey
message
account.proto:370uint64 rotation_id = 1
A random, non-zero, value that must be included in credential requests using the key. This value allows the server to ratchet the resulting binding identity, as reverting to the previous key will result in a new rotation ID.
Requests the parameters needed to verify with an MFA factor associated with this account.
message
account.proto:708(message has no fields)
message
account.proto:711bool has_totp = 1
/ If true, a TOTP password will be accepted for verification
optional webauthn_authentication_parameters = 2
/ If present, information required to complete a WebAuthn authentication
Returns parameters for initiating a WebAuthn registration ceremony WebAuthn credentials may only be registered for accounts without phone numbers
message
account.proto:594(message has no fields)
message
account.proto:597oneof response
params = 1
The parameters to use for a WebAuthn registration ceremony
too_many_mfa_keys = 2
The authenticated account already has too many MFA keys, and the caller must remove one before adding one
Provides methods for looking up Signal accounts. Callers must not provide identifying credentials when calling methods in this service.
Checks whether an account with the given service identifier exists.
message
account.proto:322optional service_identifier = 1
The service identifier of an account that may or may not exist.
message
account.proto:327bool account_exists = 1
True if an account exists with the given service identifier or false if no account was found.
rpc GetCapabilities (, )
account.proto:138Gets the publicly-visible capabilities enabled on the account identified by the provided ACI.
message
account.proto:502optional account_identifier = 1
The ACI of the account for which to get capabilities.
oneof authentication
bytes unidentified_access_key = 2
The unidentified access key for the targeted account.
bytes group_send_token = 3
A group send endorsement token for the targeted account.
message
account.proto:515oneof response
capabilities = 1
A list of capabilities enabled on the account.
not_found = 2
failed_unidentified_authorization = 3
rpc LookupUsernameHash (, )
account.proto:131Finds the service identifier of the account associated with the given username hash.
message
account.proto:333bytes username_hash = 1
A 32-byte username hash for which to find an account.
message
account.proto:338oneof response
service_identifier = 1
The service identifier associated with the provided username hash.
not_found = 2
No account was found for the provided username hash.
rpc LookupUsernameLink (, )
account.proto:134Finds the encrypted username identified by a given username link handle.
message
account.proto:348bytes username_link_handle = 1
The link handle for which to find an encrypted username. Link handles are 16-byte representations of UUIDs.
message
account.proto:354oneof response
bytes username_ciphertext = 1
The ciphertext of the username identified by the provided link handle.
not_found = 2
No username was found for the provided link handle.
message
account.proto:492Used in: ,
repeated common.DeviceCapability capabilities = 1
A list of capabilities enabled on the account.
message
account.proto:574Used in:
uint32 key_id = 1
The account-specific identifier for the newly-confirmed TOTP key
message
account.proto:230Used in:
bytes username_link_handle = 2
The server-generated username link handle for the newly-confirmed username.
message
account.proto:463A username/password pair for authenticating with an external service.
Used in:
string username = 1
A username that can be presented to authenticate with the external service.
string password = 2
A password that can be presented to authenticate with the external service.
message
account.proto:638Used in:
uint32 key_id = 1
An account-specific identifier for the new WebAuthn key
message
account.proto:540Used in:
bytes key = 1
The raw TOTP key
optional totp_parameters = 2
The TOTP parameters associated with the generated key
message
account.proto:164Used in:
uint64 level = 1
The backup level of the account
uint64 expiration_epoch_seconds = 2
When the backup entitlement expires, in number of seconds since epoch
message
account.proto:153Used in:
string badge_id = 1
The id of the badge the account is entitled. Metadata to display for badges may be obtained by cross-referencing badge ids with RemoteConfiguration.GetBadges.
uint64 expiration_epoch_seconds = 2
When the badge expires, in number of seconds since epoch
bool visible = 3
Whether the badge is currently configured to be visible
message
account.proto:661Used in:
bytes metadata_ciphertext = 1
The user-provided ciphertext for metadata associated with this MFA key
MfaKeyMetadata.MfaKeyType type = 2
The type of MFA factor this key is for
Used in:
MFA_KEY_TYPE_UNSPECIFIED = 0
MFA_KEY_TYPE_TOTP = 1
MFA_KEY_TYPE_WEBAUTHN = 2
message
account.proto:454Information about the current Registration lock and SVR credentials. With a correct PIN, the credentials can be used to recover the secret used to derive the registration lock password.
Used in:
uint64 time_remaining_millis = 1
Time remaining in milliseconds before the existing registration lock expires
optional svr2_credentials = 2
Credentials that can be used with SVR2
message
account.proto:688Used in:
(message has no fields)
message
account.proto:474A list of devices that are linked to the account but presented a stale registration ID (indicating the device has likely been replaced by another device).
Used in:
repeated uint32 stale_devices = 1
The IDs of devices that are no longer active.
message
account.proto:715Used in:
bytes challenge = 1
/ A random challenge that must be included in the authenticator response, to prevent replay attacks
uint32 timeout_seconds = 2
/ The estimated amount of time, in seconds, after which an otherwise-valid response will be rejected
repeated bytes allowed_credential_ids = 3
/ A list of credential IDs associated with this account
message
account.proto:598Used in:
bytes user_handle = 1
The "user handle" (user.id) that should be handed to the authenticator
repeated int64 allowed_algorithms = 2
The COSE IDs (https://www.iana.org/assignments/cose#algorithms) of acceptable algorithms for the created key
repeated bytes exclude_credential_ids = 3
A list of the credential IDs already registered for this account; these can be passed to candidate authenticators to tell them not to create a new key if they already have a private key matching one of these
message
account.proto:524Used in:
string algorithm = 1
The HMAC algorithm (e.g. "HmacSHA256") used by the TOTP generator
uint32 password_length = 2
The length of one-time passwords (in decimal digits) produced and expected by the TOTP generator
uint32 time_step_seconds = 3
The time step (in seconds) used by the TOTP generator
message
account.proto:203Used in: ,
(message has no fields)