User Roles and Permissions

A user's role determines what they can and cannot do in the economy. Each role has a default set of permissions. The Integration Layer enables the issuer to flexibly manage permissions. This means that each API endpoint can be enabled or disabled based on the permissions given to a particular user role. It is the responsibility of the issuer to decide how interactions will occur in their economy.
For instance, most transaction types require two steps: start and execute. If the issuer would like to create a payment scenario that involves multiple participants with different permissions, they could assign the start permission to consumers, and the execute permission to merchants for a successful transaction.
Note that only authenticated users can take on a role. Unauthenticated usage follows under the special “public” role.

📘

Example

In a very basic coin economy which involves an issuer, merchant and consumer role type, the roles configuration could look as follows:

public:
	LOGIN
	RECOVER_PASSWORD
	GET_SHOPS
	GET_SERVER_METRICS
	GET_SERVER_VERSIONS
consumer:
	GET_OWN_BALANCE
	START_QR_CHARGE
	GET_REPORTS_SELF
	GET_SHOP_INFO
	CHANGE_PASSWORD
merchant:
	GET_REPORTS_OWN
	EXECUTE_QR_PAYMENT
	REVERSE_QR_PAYMENT
	GET_SHOP_INFO
	UPDATE_SHOP_SELF
	GET_SELF_INFO
	CHANGE_PASSWORD
issuer:
	GET_REPORTS_ALL
	GET_ECONOMY_BALANCE
	ADD_USER
	SEARCH_USERS
	DEACTIVATE_ANY_USER
	GET_USER_INFO
	UPDATE_USER_INFO
	CHANGE_PASSWORD

In the above example, the GET_REPORTS_OWN permission allows the merchant to retrieve transaction reports that involve the merchant as a participant of the transaction. Similarly, the GET_SHOPS permission allows the consumer to view shop information of all the shops in the economy. All permissions stated under the public role are accessible by all roles in the economy.
These permissions will dictate what kind of interactions are possible in the economy.

Another example of permission interaction is the GET_OTHER_BALANCE permission. If given to a role, this allows a user of that role to query the balance of related accounts. Generally, this would be given to an issuer or developer account; so that the issuer can query any balance (they are the top of the user hierarchy), or, in the case of a developer, they can query the balance of any merchant that they manage.

For certain endpoints, permissions can be defined in a more fine-grained, leveled fashion. Considering the hierarchy of users that can be defined, different users may have access to different records belonging to others in the relationship chain. The levels we define are: ALL (access to all records) -> UNION (access to records of users in the same level and the parent) -> OWNED (access to records from any child and any subsequent sub-child) -> SELF (access to records belonging to the user).