Orb's Integration Layer is an integration framework composed of a collection of functions that enable integration of systems and applications across an enterprise with the Orb DLT stack. Even though the Integration Layer is not a requisite for using the Orb DLT middleware, the RESTful APIs provide programmatic access to the middleware. Partners can integrate their solutions with the API to fulfill custom economy needs like transactions, user management, reporting etc.

Using the API

The Orb Integration Layer is implemented as a RESTful server. All endpoints are described in the API reference guide. The API is compatible with all clients capable of HTTP requests. Unless otherwise noted in the reference guide, GET requests require parameters via the request's query string, and other methods (POST, PATCH, DELETE, etc) accept data via the request body in the form of a JSON document.
When sending a request, the HTTP client should also send specific headers for successful execution. Generally, all endpoints accept a Content-Type and Accepts header. The value of these headers, unless otherwise described, should be application/json. If an endpoint requires authentication, an authentication token must be sent via the X-Auth-Token header. See the authentication section for more information.

Authentication

To access an authenticated API endpoint, each user will need to provide a valid authentication token in the header of each request. An authentication token can be acquired by accessing the login endpoint. The login endpoint accepts two parameters: user_id and password. user_id and password are the credentials assigned during the user registration process.

Upon successful login, the API responds with a list of roles that the user has been assigned, the token lifetime and a boolean value to describe whether or not the user must change their password before continuing. This value can be set depending on the needs of the client. The token's lifetime extends each time it is used in subsequent requests.

The authentication token should be included in the X-Auth-Token header for all future API access.

Users in the Economy

There are a wide variety of stakeholders in an economy. Depending on the implementation scenario, stakeholders change and additional stakeholders with varying degrees of involvement may also be involved. Digital economy implementations are still in their infancy, with business models being defined and tested through numerous pilots in the market.
Currently, the Orb Integration Layer is compatible with three fundamental stakeholders - Issuer, Merchant, and Consumer. Alongside these, it can handle additional stakeholders such as vendor, developer, employees, and top-up stations. It has been designed to support hierarchical relationships between different kinds of stakeholders, such as "developer" -> "merchant" -> "employee". Each user type is part of the system-wide hierarchy and is able to perform different actions.

General Hierarchy

Issuer

An issuer is a legal entity that develops, registers and maintains the operations conducted in its coin economy. Issuers may be corporations, investment trusts, or domestic or foreign governments. Issuers are legally responsible for the obligations of the issue and for reporting financial conditions, material developments, and any other operational activities as required by the regulations of their jurisdictions. They have the highest level of authority and access to most data to help assist in overseeing the productivity and health of their custom economy. To help manage larger deployments, multiple issuer accounts can be created with different credentials.
##Consumer
A consumer is the one who spends coins to consume goods and services produced by the merchant. A consumer type user is usually the most common active participant in an economy. Their interaction extends to most stakeholders in the defined economy. They can have both the ability to initiate and execute transactions depending on the permission configuration of the system.
##Merchant
A merchant is anyone who is involved in business or trade. They are an end user that operates a shop, restaurant, etc. A merchant can transact coins with consumers (C2B/B2C) or other merchants(B2B).
##Employee
Employees are staff members that are hired by issuer, developer or merchant. A merchant’s employee can initiate instant payment refunds through the merchant management portal while an issuer’s employee can overlook the health of the economy via the issuer management portal. Depending on the permissions defined by the merchant, developer and/or issuer, an employee can have full or partial access to their respective management portals.
##Developer
Developers act as an optional merchant management layer underneath the issuer. In the event that an organization owning multiple merchants joins the economy, they are assigned the developer role. This helps minimize direct interaction between issuer and merchant and streamline settlements. In large deployments, this is essential to maintain an efficiently running economy. Note that developers are optional and issuers can choose to directly manage merchants.
##Vendor
Typically, the issuer is responsible for issuing coins within a coin economy. However, in some use cases it may be useful for the issuer to delegate issuance of a particular coin to a different—possibly external—entity. This would allow, for example, many different companies to issue their own coins without requiring them to set up or manage their own infrastructure. Non-issuer entities with the ability to issue coins are called vendors.
##Top-up Stations
Coins can be topped up by consumers at top-up stations. These are designated spots that provide an entry point for coins to be created in exchange for fiat currency to supply the economy. The responsible entity at the top-up station generates a QR code that contains charge amount which is scannable by the consumer. They are also responsible for accepting and managing cash to authorize the execution of the exchange.