Vault gRPC Documentation

November 21, 2025 · View on GitHub

Download Protocol Buffer File
- Version 1
Prerequisites
Usage
- Public Functions
- Internal Functions

Download Protocol Buffer File

To use the gRPC functions, download the protocol buffer file from the proto directory corresponding to the desired version.

Version 1

curl -O -L https://raw.githubusercontent.com/smswithoutborders/SMSwithoutborders-BE/feature/grpc_api/protos/v1/vault.proto

Prerequisites

Install Dependencies

If you're using Python, install the necessary dependencies from requirements.txt. For other languages, see Supported languages.

Tip

it's recommended to set up a virtual environment to isolate your project's dependencies.

python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt

Compile gRPC for Python

If you're using Python, compile the gRPC files with protoc to generate the necessary Python files. For other languages, see Supported languages.

python -m grpc_tools.protoc -I protos/v1 --python_out=. --grpc_python_out=. protos/v1/vault.proto

Starting the Server

Quick Start (for Development Only)

Public Server

DATA_ENCRYPTION_KEY_PRIMARY_FILE=/path/to/encryption.key \
HMAC_KEY_FILE=/path/to/hashing.key \
KEYSTORE_PATH=/path/to/key_store \
SQLITE_DATABASE_PATH=/path/to/local.db \
GRPC_PORT=6000 \
GRPC_HOST=127.0.0.1 \
python3 grpc_server.py

Internal Server

DATA_ENCRYPTION_KEY_PRIMARY_FILE=/path/to/encryption.key \
HMAC_KEY_FILE=/path/to/hashing.key \
KEYSTORE_PATH=/path/to/key_store \
SQLITE_DATABASE_PATH=/path/to/local.db \
GRPC_INTERNAL_PORT=6099 \
GRPC_HOST=127.0.0.1 \
python3 grpc_internal_server.py

Usage

Public Functions

These functions are exposed to external clients for interaction with the vault.

Create an Entity

An entity represents a user or client in the vault.

Initiate Creation

Before creating an entity, you must prove ownership of the phone number you intend to use. This step ensures the security and authenticity of the entity creation process.

Request

request CreateEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the entity (optional). It should be in E164 format. e.g., +237123456789.
email_address	string	The email address associated with the entity (optional).
country_code	string	The ISO 3166-1 alpha-2 code associated with the phone number. e.g., `CM` for Cameroon.
password	string	A secure password for the entity.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
client_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.
captcha_token	string	The captcha token to be verified.

Response

response CreateEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
requires_ownership_proof	bool	An indicator if proof of ownership is required. `true` if required, `false` otherwise.
next_attempt_timestamp	int32	The next available time to request another proof of ownership (in Unix seconds) if the first attempt fails.
message	string	A response message from the server.

Method

method CreateEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/CreateEntity <payload.json

Sample payload.json

{
  "country_code": "CM",
  "phone_number": "+237123456789",
  "email_address": "mail@example.com",
  "password": "Password@123",
  "client_publish_pub_key": "x25519 client publish public key",
  "client_device_id_pub_key": "x25519 client device_id public key"
}

Sample response

{
  "requiresOwnershipProof": true,
  "message": "OTP sent successfully. Check your phone for the code.",
  "nextAttemptTimestamp": 1717323582
}

Complete Creation

Warning

Ensure that you have completed the Initiate Creation step before executing this step.

Request

request CreateEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the entity (optional). It should be in E164 format. e.g., +237123456789.
email_address	string	The email address associated with the entity (optional).
country_code	string	The ISO 3166-1 alpha-2 code associated with the phone number. e.g., `CM` for Cameroon.
password	string	A secure password for the entity.
ownership_proof_response	string	The proof response from the previous step.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
client_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.

Response

response CreateEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
server_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
server_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.
long_lived_token	string	A token for the authenticated session, to be used for subsequent requests.

Method

method CreateEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/CreateEntity <payload.json

Sample payload.json

{
  "country_code": "CM",
  "phone_number": "+237123456789",
  "email_address": "mail@example.com",
  "password": "Password@123",
  "client_publish_pub_key": "x25519 client publish public key",
  "client_device_id_pub_key": "x25519 client device_id public key",
  "ownership_proof_response": "123456"
}

Sample response

{
  "longLivedToken": "long_lived_token",
  "serverPublishPubKey": "x25519 server publish public key",
  "serverDeviceIdPubKey": "x25519 server publish public key",
  "message": "Entity created successfully"
}

Authenticate an Entity

An entity represents a user or client in the vault.

Warning

Repeated incorrect password attempts will trigger a dynamic rate limit and return an UNAVAILABLE status code for this function.

Initiate Authentication

This step involves verifying the phone number and password, triggering a proof of ownership for the phone number.

Request

request AuthenticateEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the entity (optional). It should be in E164 format. e.g., +237123456789.
email_address	string	The email address associated with the entity (optional).
password	string	A secure password for the entity.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
client_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.
captcha_token	string	The captcha token to be verified.

Response

response AuthenticateEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
requires_ownership_proof	bool	An indicator if proof of ownership is required. `true` if required, `false` otherwise.
requires_password_reset	bool	An indicator if a user must reset their password. `true` if required, `false` otherwise.
next_attempt_timestamp	int32	The next available time to request another proof of ownership (in Unix seconds) if the first attempt fails.
message	string	A response message from the server.

Method

method AuthenticateEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/AuthenticateEntity <payload.json

Sample payload.json

{
  "phone_number": "+237123456789",
  "email_address": "mail@example.com",
  "password": "Password@123",
  "client_publish_pub_key": "x25519 client publish public key",
  "client_device_id_pub_key": "x25519 client device_id public key"
}

Sample response

{
  "requiresOwnershipProof": true,
  "message": "OTP sent successfully. Check your phone for the code.",
  "nextAttemptTimestamp": 1717323582
}

Complete Authentication

Warning

Ensure that you have completed the Initiate Authentication step before executing this step.

Request

request AuthenticateEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the entity (optional). It should be in E164 format. e.g., +237123456789.
email_address	string	The email address associated with the entity (optional).
password	string	A secure password for the entity.
ownership_proof_response	string	The proof response from the previous step.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
client_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.

Response

response AuthenticateEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
server_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
server_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.
long_lived_token	string	A token for the authenticated session, to be used for subsequent requests.

Method

method AuthenticateEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/AuthenticateEntity <payload.json

Sample payload.json

{
  "phone_number": "+237123456789",
  "email_address": "mail@example.com",
  "password": "Password@123",
  "client_publish_pub_key": "x25519 client publish public key",
  "client_device_id_pub_key": "x25519 client device_id public key",
  "ownership_proof_response": "123456"
}

Sample response

{
  "longLivedToken": "long_lived_token",
  "serverPublishPubKey": "x25519 server publish public key",
  "serverDeviceIdPubKey": "x25519 server publish public key",
  "message": "Entity authenticated successfully!"
}

Create Bridge Entity

An entity represents a user or client in the vault.

Initiate Bridge Creation

Before creating a bridge entity, you must prove ownership of the phone number you intend to use. This step ensures security and authenticity in the entity creation process.

Request

request CreateBridgeEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the bridge entity. It should be in E164 format, e.g., +237123456789.
country_code	string	The ISO 3166-1 alpha-2 code associated with the phone number. e.g., `CM` for Cameroon.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.

Response

response CreateBridgeEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates whether the operation was successful. `true` or `false`.

Method

method CreateBridgeEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/CreateBridgeEntity <payload.json

Sample payload.json

{
  "country_code": "CM",
  "phone_number": "+237123456789",
  "client_publish_pub_key": "x25519 client publish public key"
}

Sample response

{
  "success": true,
  "message": "Bridge entity created successfully."
}

Complete Bridge Creation

Warning

Ensure that you have completed the Initiate Bridge Creation step before executing this step.

Request

request CreateBridgeEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the bridge entity. It should be in E164 format. e.g., +237123456789.
country_code	string	The ISO 3166-1 alpha-2 code associated with the phone number. e.g., `CM` for Cameroon.
ownership_proof_response	string	The proof response from the previous step.

Response

response CreateBridgeEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates whether the operation was successful. `true` or `false`.

Method

method CreateBridgeEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/CreateBridgeEntity <payload.json

Sample payload.json

{
  "country_code": "CM",
  "phone_number": "+237123456789",
  "ownership_proof_response": "123456"
}

Sample response

{
  "success": true,
  "message": "Bridge entity creation completed successfully."
}

Authenticate Bridge Entity

An entity represents a user or client in the vault.

Request

request AuthenticateBridgeEntityRequest

Field	Type	Description
phone_number	string	The phone number associated with the bridge entity.

Response

response AuthenticateBridgeEntityResponse

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates whether authentication was successful.

Method

method AuthenticateBridgeEntity

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/AuthenticateBridgeEntity <payload.json

Sample payload.json

{
  "phone_number": "+237123456789"
}

Sample response

{
  "success": true,
  "message": "Bridge entity authenticated successfully."
}

List an Entity's Stored Tokens

This method retrieves the stored tokens for a given entity.

Request

request ListEntityStoredTokensRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
long_lived_token	string	The long-lived token for the authenticated session, used to identify the entity.

Optional fields:

Field	Type	Description
migrate_to_device	bool	Indicates if the token should be removed from the cloud and sent to the device.

Response

response ListEntityStoredTokensResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
stored_tokens	array	A list of stored tokens. Each token object may contain various fields. See Token Object for details.
message	string	A response message from the server.

Token Object

message Token

Field	Type	Description
platform	string	The platform associated with the token.
account_identifier	string	The unique identifier of the account associated with the token.
account_tokens	map<string, string>	Contains the access, refresh, and ID tokens with keys: `access_token`, `refresh_token`, and `id_token`.
is_stored_on_device	bool	Indicates if the token is already stored on the device.

Method

method ListEntityStoredTokens

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d '{"long_lived_token": "long_lived_token"}' \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/ListEntityStoredTokens

Sample response

{
  "stored_tokens": [
    {
      "account_identifier": "my_x_handle",
      "platform": "x"
    },
    {
      "account_identifier": "example@gmail.com",
      "platform": "gmail"
    }
  ],
  "message": "Tokens retrieved successfully."
}

Delete An Entity

This function deletes an entity.

Warning

Ensure all stored tokens associated with this entity have been revoked before using this function. Failure to do so will result in a FAILED_PRECONDITION error.

Request

request DeleteEntityRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
long_lived_token	string	The long-lived token for the authenticated session.

Response

response DeleteEntityResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates if the operation was successful.

Method

method DeleteEntity

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d '{"long_lived_token": "long_lived_token"}' \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/DeleteEntity

Sample response

{
  "message": "Entity deleted successfully.",
  "success": true
}

Reset an Entity's Password

In case of forgotten passwords, they can be reset with the following steps.

Initiate Reset

This step involves verifying the phone number, triggering a proof of ownership for the phone number.

Request

request ResetPasswordRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the entity (optional). It should be in E164 format. e.g., +237123456789.
email_address	string	The email address associated with the entity (optional).
new_password	string	A new secure password for the entity.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
client_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.
captcha_token	string	The captcha token to be verified.

Response

response ResetPasswordResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
requires_ownership_proof	bool	An indicator if proof of ownership is required. `true` if required, `false` otherwise.
next_attempt_timestamp	int32	The next available time to request another proof of ownership (in Unix seconds) if the first attempt fails.
message	string	A response message from the server.

Method

method ResetPassword

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/ResetPassword <payload.json

Sample payload.json

{
  "phone_number": "+237123456789",
  "email_address": "mail@example.com",
  "new_password": "Password@123",
  "client_publish_pub_key": "x25519 client publish public key",
  "client_device_id_pub_key": "x25519 client device_id public key"
}

Sample response

{
  "requiresOwnershipProof": true,
  "message": "OTP sent successfully. Check your phone for the code.",
  "nextAttemptTimestamp": 1717323582
}

Complete Reset

Warning

Ensure that you have completed the Initiate Reset step before executing this step.

Request

request ResetPasswordRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
phone_number	string	The phone number associated with the entity (optional). It should be in E164 format. e.g., +237123456789.
email_address	string	The email address associated with the entity (optional).
new_password	string	A new secure password for the entity.
ownership_proof_response	string	The proof response from the previous step.
client_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
client_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.

Response

response ResetPasswordResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
server_publish_pub_key	string	An `X25519` public key for publishing, `base64 encoded`.
server_device_id_pub_key	string	An `X25519` public key for device ID, `base64 encoded`.
long_lived_token	string	A token for the authenticated session, to be used for subsequent requests.

Method

method ResetPassword

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/ResetPassword <payload.json

Sample payload.json

{
  "phone_number": "+237123456789",
  "email_address": "mail@example.com",
  "new_password": "Password@123",
  "client_publish_pub_key": "x25519 client publish public key",
  "client_device_id_pub_key": "x25519 client device_id public key",
  "ownership_proof_response": "123456"
}

Sample response

{
  "longLivedToken": "long_lived_token",
  "serverPublishPubKey": "x25519 server publish public key",
  "serverDeviceIdPubKey": "x25519 server publish public key",
  "message": "Password reset successfully!"
}

Update an entity's Password

This method updates the password for a given entity.

Warning

Repeated incorrect password attempts will trigger a dynamic rate limit and return an UNAVAILABLE status code for this function.

Request

request UpdateEntityPasswordRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
long_lived_token	string	The long-lived token for the authenticated session, used to identify the entity.
current_password	string	The current password of the entity.
new_password	string	The new password of the entity.

Response

response UpdateEntityPasswordResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates if the operation was successful.

Method

method UpdateEntityPassword

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/UpdateEntityPassword <payload.json

Sample payload.json

{
  "current_password": "current_password",
  "long_lived_token": "long_lived_token",
  "new_password": "new_password."
}

Sample response

{
  "message": "Password updated successfully.",
  "success": true
}

Internal Functions

These functions handle internal operations and are not directly exposed to external clients.

Store an Entity's Token

This step involves storing tokens securely for the authenticated entity.

Request

request StoreEntityTokenRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
long_lived_token	string	The long-lived token for the authenticated session.
token	string	The token to be stored.
platform	string	The platform from which the token is being issued. (e.g., "gmail").
account_identifier	string	The identifier of the account associated with the token.

Optional fields:

Field	Type	Description
code_verifier	string	A cryptographic random string used in the PKCE flow.

Response

response StoreEntityTokenResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	boolean	Indicates if the operation was successful.

Method

method StoreEntityToken

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/StoreEntityToken <payload.json

Sample payload.json

{
  "long_lived_token": "long_lived_token",
  "authorization_code": "oauth2_code",
  "platform": "gmail",
  "protocol": "oauth2"
}

Sample response

{
  "message": "Token stored successfully.",
  "success": true
}

Get Entity Access Token

This function retrieves an entity's access token.

Request

request GetEntityAccessTokenRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
device_id or phone_number or long_lived_token	string	The unique identifier of the device or the phone number or the long lived token used by the entity.
platform	string	The platform from which the token is being issued. (e.g., "gmail").
account_identifier	string	The identifier of the account associated with the token.

Response

response GetEntityAccessTokenResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates if the operation was successful.
token	string	The retrieved token associated with the entity for the specified platform.

Method

method GetEntityAccessToken

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d '{"device_id": "device_id", "platform": "gmail", "account_identifier": "sample@mail.com"}' \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/GetEntityAccessToken

Sample response

{
  "message": "Successfully fetched tokens",
  "success": true,
  "token": "retrieved_token"
}

Decrypt Payload

This function handles decrypting payload content.

Request

request DecryptPayloadRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
device_id or phone_number	string	The unique identifier of the device or the phone number used by the entity.
payload_ciphertext	string	The encrypted payload ciphertext that needs to be decrypted.

Response

response DecryptPayloadResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates if the operation was successful.
payload_plaintext	string	The decrypted payload plaintext.

Method

method DecryptPayload

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d '{"device_id": "device_id", "payload_ciphertext": "encrypted_payload"}' \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/DecryptPayload

Sample response

{
  "message": "Successfully decrypted payload",
  "success": true,
  "payload_plaintext": "Decrypted payload content"
}

Encrypt Payload

This function handles the encryption of payload content.

Request

request EncryptPayloadRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
device_id	string	The unique identifier of the device used by the entity.
payload_plaintext	string	The plaintext payload content to be encrypted.

Response

response EncryptPayloadResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
payload_ciphertext	string	The encrypted payload ciphertext.
success	bool	Indicates if the operation was successful.

Method

method EncryptPayload

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d '{"device_id": "device_id", "payload_plaintext": "plaintext_payload"}' \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/EncryptPayload

Sample response

{
  "message": "Successfully encrypted payload.",
  "payload_ciphertext": "encrypted_payload",
  "success": true
}

Update An Entity's Token

This function updates tokens associated with an entity.

Request

request UpdateEntityTokenRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
device_id or phone_number	string	The unique identifier of the device or the phone number used by the entity.
token	string	The new token to be updated for the entity.
platform	string	The platform from which the token is being updated. (e.g., "gmail").
account_identifier	string	The identifier of the account associated with the token.

Response

response UpdateEntityTokenResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates if the operation was successful.

Method

method UpdateEntityToken

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d '{"device_id": "device_id", "token": "new_token", "platform": "gmail", "account_identifier": "sample@mail.com"}' \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/UpdateEntityToken

Sample response

{
  "message": "Token updated successfully.",
  "success": true
}

Delete An Entity's Token

This function deletes tokens associated with an entity.

Request

request DeleteEntityTokenRequest

Important

The table lists only the required fields for this step. Other fields will be ignored.

Field	Type	Description
long_lived_token	string	The long-lived token for the authenticated session.
platform	string	The platform from which the token is being updated. (e.g., "gmail").
account_identifier	string	The identifier of the account associated with the token.

Response

response DeleteEntityTokenResponse

Important

The table lists only the fields that are populated for this step. Other fields may be empty, omitted, or false.

Field	Type	Description
message	string	A response message from the server.
success	bool	Indicates if the operation was successful.

Method

method DeleteEntityToken

Tip

The examples below use grpcurl.

Note

Here is what a successful response from the server looks like.

The server would return a status code of 0 OK if the API transaction goes through without any friction. Otherwise, it will return any other code out of the 17 codes supported by gRPC.

Sample request

grpcurl -plaintext \
    -d @ \
    -proto protos/v1/vault.proto \
localhost:6000 vault.v1.Entity/DeleteEntityToken <payload.json

Sample payload.json

{
  "long_lived_token": "long_lived_token",
  "platform": "gmail",
  "account_identifier": "sample@mail.com"
}

Sample response

{
  "message": "Token deleted successfully.",
  "success": true
}