Changes

📘

In this article

• This article is intended to supplement the existing API reference for the Changes endpoint
• Details about Changes API and what entities can be set, along with the supported actions and fields for each entity.
• An example of how to structure the body for a change.

Introduction

Taurus-PROTECT has a robust change approval system where each change must be approved by admins or in some cases, superadmins. This change management system is powered by the Changes endpoints. This endpoint can be used to make changes to users, wallets, whitelisted addresses, and more.

When reading the API Reference, you will notice that creating changes via the API requires telling protect which action and entity you wish to change. Depending on the entity, different actions are supported (usually create, update and delete).

Changes in Protect

Administration of PROTECT is managed through change requests. When a setting is changed in the GUI, a change is then visible for approval . Changing a user's signing method, adding whitelisted addresses, or updating prices require a change request and 4-eyes approval process, among others.

The high level change process is as follows:

Important considerations:

• Once a change has been created, it cannot be edited. You must reject the change and create a new one.
• A change can be rejected by the same user that created it.
• A change can only be approved by a different user with appropriate permissions.
  • Example: A change to Price requires the Price Managerrole. Only users with the Price Manager role will be able to approve this change.
• Some changes, such as group associations or public key changes, will generate a separate change in the governance rules. Governance rule changes require approvals by the superadmin quorum.

Entity specific processing rules

The changes API implements CRUD semantics on various entities, where each entity type has its own processing rules. Here are some of the entity-specific rules that apply. Note that this list is non-exhaustive.

All Entities

• You cannot create a change which already exists. The API will return an error.
• Once a change has been created, it cannot be edited. You must reject the change and create a new one.
• Once approved, changes are applied immediately by PROTECT.

User

• Super admin users cannot be deleted.
• A user's Super Admin role cannot be removed.
• Only firstname, lastname, email, username, status and roles can be changed for Super Admin users.
• All users must have an externalUserID (typically an email address).

Groups

• If SSO is enabled, groups changed via SCIM cannot be changed manually.
• Groups are automatically reset for SSO users on the next login, creating an change request.

Account Freezes

• There are two different endpoints for account freezes depending on if a blockchain is account based (e.g., Ethereum) or utxo based (e.g., Bitcoin).

Making changes via the API

To create a change using the API, follow these steps:

1. Making a change with the Create a change endpoint.
2. With the other admin, calling the List changes for approval endpoint.

   ⚠️

   Ensure proper review

   This endpoint returns all pending changes in the changes field. These must be carefully validated prior to approving. Failure to do so could result in an unintended change being approved.

3. Calling Approve a changeendpoint and passing in the ID of the changes you wish to approve.
   1. Alternately you may approve all pending changes by using the Approve changesendpoint. The above warning should be taken into careful consideration.

📘

Delete

You will notice in the API reference that passing change in the body is not mandatory. This is becauseDelete does not require a change body however does require an entity and an entityID.

Entity, action, and field mappings

The table below shows a list of valid entities, their supported actions and their valid fields. Fields are supplied in thechanges property. Note that not all fields may be required and that each entity will have it's own validation. If you have further questions about the validation for an entity, please do not hesitate to reach out to support.

Example

If you wanted to set a price source to CryptoCompare (after making a manual adjustment), you would send a POST request to Create a change with the following body:

{
  "action": "update", // again, the table above shows list of valid actions for each entity.
  "entity": "price",
  "changes": {
    "blockchain": "BTC", // each change entity has it's own backend validation.
    "currencyfrom": "BTC",
    "currencyto": "CHF",
    "source": "cryptocompare.com"
  }
}

The response if successful would return the result ID and a change would be available at the List changes for approval endpoint. If you query this endpoint and do not see results. Ensure you use a different user that has the appropriate permissions to review the change (in this example, Price Manager).

{
  "result": {
    "id": "12345"
  }
}