Skip to content

grpc.md

Latest commit

 

History

History
1826 lines (1318 loc) · 54.9 KB

grpc.md

File metadata and controls

1826 lines (1318 loc) · 54.9 KB

Vault gRPC Documentation

Table of Contents

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
}