User Data

User data is the foundation of the zkp.services solution. On this page, we will dive into the API requests that our dApp makes to the backend API to manage your data securely. Our serverless dApp frontend also allows you to specify your own custom URL for your data provider. In order to interact with the protocol through this particular frontend, the data source needs to be compliant with these API guidelines and the custom URL needs to be specified when logging in.

The structure of user data

Our data model is an extremely versatile JSON object that gives way to endless data points a user can store for countless different services. As such, below, we will provide an example of a potential data structure for user data, but note that none of the fields in the data object are specifically required. We will support other data and object types in the future.

Properties of JSON object

Name
id
Type
string
Description
Unique wallet address identifier for the user.
Name
password
Type
string
Description
The password associated with the user.
Name
2fa_password
Type
string
Description
The 2FA password associated with the user.
Name
contract_password
Type
string
Description
The smart contract password associated with the user.
Name
chain_data
Type
JSON Object[]
Description
JSON object containing the entire dataset for a specific user, where each chain ID they have onboarded to is a child of this object.

POST/userdata, action: "get_item"

Retrieve user data

This endpoint allows you to retrieve either the entire or a subset of the "data" object for the self-user.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_item".
Name
chain_id
Type
string
Description
The chain id of the dataset to be pulled.

Optional attributes

Name
key
Type
string
Description
The flattened JSON key for the property trying to be retrieved, for example, "medical records - pharmacy central melbourne.data.active prescriptions". If not provided, it will return the entire data set for the user.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "get_item",
      "password": "abc123",
      "chain_id": "0xa869",
      "key": "medical records"

}'

Response

{
    "medical records": {
        "usage": "Antibiotic",
        "dosage": "250mg to 500mg every 8 hours or 875mg every 12 hours",
        "refills remaining": "3 for 50 x 1g or equivalent"
    }
}

POST/userdata, action: "create_item"

Create a user and dataset

This endpoint allows you to create a new user and associated dataset. You can only add a user from a wallet that you own.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "create_item".
Name
chain_data
Type
string
Description
Contains the initial JSON dataset for a user. Can contain multiple chains.
Name
2fa_password
Type
string
Description
The 2FA password of the user.
Name
contract_password
Type
string
Description
The smart contract password of the user.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "chain_id": "0xa869",
    "password": "abc123",
    "action": "create_item",
    "contract_password": "abc123",
    "2fa_password": "abc123",
    "chain_data": {
        "0xa869": {
            "rsa_enc_pub_key": "<public key>",
            "rsa_enc_priv_key": "<private key>",
            "rsa_sign_pub_key": "<public key>",
            "rsa_sign_priv_key": "<private key>",
            "public_info": "Hello"
        }
    }
}'

Response

Item created successfully!

PUT/userdata, action: "update_item"

Update a users data

This endpoint allows you to update the data object for a specific user.

This is an incremental function, meaning that you supply the data {} json object containing only the fields you wish to update. The fields you do not specify will not be modified. If you specify a field that does not exist, it will be created.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "update_item".
Name
data
Type
JSON Object
Description
Contains the updated data for the user.
Name
chain_id
Type
string
Description
The current chain ID.

Request

PUT

/userdata

curl --location --request PUT 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "update_item",
      "password": "abc123",
      "chain_id": "0xa869",
      "data": {
          "myki": {
              "balance": "A$11.00"
          }
      }
}'

Response

{
    "data": {
        "myki": {
            "balance": "A$200"
        },
        "id": {
            "name": "Johnathan Doe",
            "DOB": "25/03/2002"
        },
        "NAB": {
            "savings": "A$2400.00"
        }
    }
}

PUT/userdata, action: "update_item"

Update password

This endpoint allows you to update your password.

Authentication is required

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The current password of the user.
Name
action
Type
string
Description
The action of this request, which is "update_password".
Name
new_password
Type
string
Description
The new password.

Request

PUT

/userdata

curl --location --request PUT 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data-raw '{
        "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
        "new_password": "abc123",
        "password": "abc123",
        "action": "update_password"
}'

Response

"Password updated successfully!"

POST/userdata, action: "login"

This endpoint allows you to authenticate with our dApp.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "login".
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "login",
      "password": "pop",
      "chain_id": "0xa869"
}'

Response

"User authenticated successfully."

POST/userdata, action: "add_request"

Add request

This endpoint allows you to add a new request for data for a specific user.

Authentication is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "add_request".
Name
request
Type
JSON Object
Description
A JSON object containing the request.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "action": "add_request",
    "password": "abc123",
    "request": {
        "requestID": "20716965315651526627121156873417490254946957749778301596059776852466841093871",
        "address_sender": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
        "address_receiver": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
        "attach_token": false,
        "key": "49|imnkx;!9k{9YLMaPR(]eY",
        "chainID": "0xa869",
        "operation": "update",
        "field": "medical data",
        "updated_data": {
            "blood type": "AB"
        },
        "limit": "86400",
        "require2FA": false,
        "response_fee": "10",
        "timestamp": "1701715461439",
        "twoFARequestID": ""
    }
}'

Response

"Request added successfully"

POST/userdata, action: "add_response"

Add response

This endpoint allows you to add a new response for data/update for a specific user.

Authentication is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "add_response".
Name
response
Type
JSON Object
Description
A JSON object containing the response.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "action": "add_response",
    "password": "abc123",
    "response": {
        "responseID": "20716965315651526627121156873417490254946957749778301596059776852466841093871",
        "address_sender": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
        "address_receiver": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
        "attach_token": false,
        "key": "49|imnkx;!9k{9YLMaPR(]eY",
        "chainID": "0xa869",
        "operation": "update",
        "field": "medical data",
        "updated_data": {
            "blood type": "AB"
        },
        "limit": "86400",
        "require2FA": false,
        "timestamp": "1701715461439",
        "twoFARequestID": ""
    }
}'

Response

"Response added successfully"

POST/userdata, action: "get_available_dashboard"

Retrieve user available dashboard items

This endpoint allows you to the list of services available for a particular user's dashboard.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_available_dashboard".
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "get_dashboard",
      "password": "abc123",
      "chain_id": "0xa869"
}'

Response

["myki", "commbank", "NAB"]

POST/userdata, action: "get_dashboard"

Retrieve user current dashboard items

This endpoint allows you to access the list of currently selected services for a particular user's dashboard.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_dashboard".
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "get_available_dashboard",
      "password": "abc123",
      "chain_id": "0xa869"
}'

Response

["myki", "commbank"]

POST/userdata, action: "add_to_dashbaord"

Add a service to a users dashboard

This endpoint allows you to add a particular service to a user's dashboard.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "add_to_dashboard".
Name
service
Type
string
Description
The name of the service you want to add to the user's dashboard.
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "add_to_dashboard",
      "password": "abc123",
      "service": "id",
      "chain_id": "0xa869"
}'

Response

"Item added to dashboard successfully!"

DELETE/userdata, action: "remove_from_dashboard"

Remove a service from a users dashboard

This endpoint allows you to remove a particular service from a user's dashboard.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "remove_from_dashboard".
Name
service
Type
string
Description
The name of the service you want to remove from the user's dashboard.
Name
chain_id
Type
string
Description
The current chain ID.

Request

DELETE

/userdata

curl --location --request DELETE 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "remove_from_dashboard",
      "password": "abc123",
      "service": "id",
      "chain_id": "0xa869"
}'

Response

"Item removed from dashboard successfully!"

POST/userdata, action: "add_crosschain_transaction"

Add a crosschain transaction

This endpoint allows you to add a new crosschain transaction.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "add_crosschain_transaction".
Name
type
Type
string
Description
The type of the parameter that is to be synced to another chain.
Name
param_key
Type
string
Description
The key of the parameter specified.
Name
source_chain_id
Type
string
Description
The chain ID of the source chain.
Name
target_chain_id
Type
string
Description
The chain ID of the target chain.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "password": "abc123",
    "target_chain_id": "0x13881",
    "source_chain_id": "0xa869",
    "action": "add_crosschain_transaction",
    "param_key": "id",
    "type": "data",
    "ccid": "1283748234"
}'

Response

"Crosschain transaction added successfully!"

POST/userdata, action: "get_crosschain_transaction"

Get crosschain transactions

This endpoint allows you to retrieve the list of crosschain transactions for a specific chain.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_crosschain_transaction".
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "get_crosschain_transaction",
      "password": "pop",
      "chain_id": "0xa869"
}'

Response

[{"last_updated": "1701375571", "ccid": "1283748234", "parameter_key": "hair", "target_chain": "0x13881", "parameter": "data", "source_chain": "0xa869"}]

POST/userdata, action: "get_incoming"

Get incoming

This endpoint allows you to retrieve all incoming requests and responses for a specific chain.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_incoming".
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "action": "get_incoming",
    "chain_id": "0xa869",
    "password": "abc123"
}'

Response

{"requests_received": [{"address_sender": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "last_updated": "1701720851", "salt": "i5YTE52s:Ev;7h%;do5LQL1d", "response_fee": "10", "updated_data": {"thisisatest": {"testarray": ["value1", "value2", "value3"]}}, "twoFARequestID": "", "attach_token": false, "address_receiver": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "field": "thisisatest", "chainID": "0xa869", "requestID": "2268977444251872856677282658047689095817294886379324949820237564846081429917", "limit": "600", "require2FA": false, "operation": "update", "key": "Z>SmAr{oBq<17m;1g.x}.P+!", "timestamp": "1701720838237"}], "responses_received": [{"address_sender": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "last_updated": "1701720904", "salt": "i5YTE52s:Ev;7h%;do5LQL1d", "response_fee": "10", "updated_data": {"thisisatest": {"testarray": ["value1", "value2", "value3"]}}, "twoFARequestID": "", "address_receiver": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "field": "thisisatest", "chainID": "0xa869", "limit": "600", "require2FA": false, "operation": "update", "key": "Z>SmAr{oBq<17m;1g.x}.P+!", "responseID": "2268977444251872856677282658047689095817294886379324949820237564846081429917", "timestamp": "1701720901897"}]}

POST/userdata, action: "get_outgoing"

Get outgoing

This endpoint allows you to retrieve all outgoing requests and responses for a specific chain.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_outgoing".
Name
chain_id
Type
string
Description
The current chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "action": "get_outgoing",
    "password": "abc123",
    "chain_id": "0xa869"
}'

Response

{"requests_sent": [{"address_sender": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "last_updated": "1701720851", "salt": "i5YTE52s:Ev;7h%;do5LQL1d", "response_fee": "10", "updated_data": {"thisisatest": {"testarray": ["value1", "value2", "value3"]}}, "twoFARequestID": "", "attach_token": false, "address_receiver": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "field": "thisisatest", "chainID": "0xa869", "requestID": "2268977444251872856677282658047689095817294886379324949820237564846081429917", "limit": "600", "require2FA": false, "operation": "update", "key": "Z>SmAr{oBq<17m;1g.x}.P+!", "timestamp": "1701720838237"}], "responses_sent": [{"address_sender": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "last_updated": "1701720904", "salt": "i5YTE52s:Ev;7h%;do5LQL1d", "response_fee": "10", "updated_data": {"thisisatest": {"testarray": ["value1", "value2", "value3"]}}, "twoFARequestID": "", "address_receiver": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d", "field": "thisisatest", "chainID": "0xa869", "limit": "600", "require2FA": false, "operation": "update", "key": "Z>SmAr{oBq<17m;1g.x}.P+!", "responseID": "2268977444251872856677282658047689095817294886379324949820237564846081429917", "timestamp": "1701720901897"}]}

POST/userdata, action: "add_new_chain"

Add new chain

This endpoint allows you to onboard onto a new chain.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "add_new_chain".
Name
old_chain_id
Type
string
Description
The current chain ID.
Name
chain_id
Type
string
Description
The new chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
    "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
    "password": "maeve",
    "chain_id": "0x13881",
    "old_chain_id": "0xa869",
    "action": "add_new_chain"
}'

Response

"New chain added successfully."

POST/userdata, action: "get_chain_data"

Get chain data

This endpoint allows you to get the full set of chain data for a user, including all chains.

Note the response from this is very large, which is why it is omitted.

Authorization is required.

Required attributes

Name
id
Type
string
Description
The wallet address of the user.
Name
password
Type
string
Description
The password of the user.
Name
action
Type
string
Description
The action of this request, which is "get_chain_data".
Name
chain_id
Type
string
Description
The new chain ID.

Request

POST

/userdata

curl --location 'https://api.zkp.services/userdata' \
--header 'Content-Type: application/json' \
--data '{
      "id": "0x84713a3a001E2157d134B97C59D6bdAb351dd69d",
      "action": "get_chain_data",
      "password": "pop",
      "chain_id": "0xa869"
}'

Response

"{"props": {"2fa_password": "pop", "contract_password": "pop", "onboarded_chains": ["0x13881", "0xa869"], "rsa_enc_pub_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAo5uuPoztcZVMV0jr2Rw5rxqUFQ+C+l8v5tgJpKIkC0A2GpVviee70JsPD2wZjBB80HliBJPuzKtk/fapHO3W2udJAzWvPJN20Tj4NdxIIaB+ymOwVKFP1JIivTwqx0f13vBXuke2YcBT9zv4dyz8mH4UVNNxssPXSi02Ajp+MPjSR2FI+Le8frXvVyAF8HkQgoFW+3Tlw/fRyIW54zx353pmDRDFLhCsNA2a91abYyt/RmklkWVjz+i2d9Je6OnA9lTO7OWWx0tIDCIdEN6z6Qdiu87+cBlUDOA0jb/Il+atEQ6Rrb8CKHTGH4ZCdN7sx/fscPYGMmkb5d/ofAWWsQIDAQAB====", "rsa_sign_pub_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnaGT6fhjMCWIL1KIp2V0Z0sXGO9qqDxvgUDOmA4wCoOK2h2mIAMLJ0BYRySykpBk9k3eYGSPkCihYz1xW4yIWwsNSlk8wqQ3NeiY/3dDl2yeoXlIX6+TDpPrtOVRI35k2ydVDja9vov227qiaOc/xSSfc3WLQY6/spFRjLPJkAdJF6ZXlKaJ2SgQrNME9qYNCp7/KzdMTpAn+waEfGBwzDNxqgFslUg0ZYNtTtkmOieFsigxYjSvl/RoQKk45leRQLlDYm6Hmw3EnsRgFRLSE3eMVqguQeUbACGP1CnzS43GdUo8MS956WRUXedKlPiW8n15p6w7Rt+NTlZzu0jX1QIDAQAB====", "public_info": "Mi chiamo Ploppini, il sono cane del tartufo"}}"