The Ownera APIs are a set of API’s which are the entry point to interact with the Ownera Network.
Those API’s will be used by nodes and application providers to build the applications and tools around the network that will serve the ecosystem and market participants.
The Ownera API is conforms to REST. It has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors. To make the API as explorable as possible, this documentation has a test mode. You can freely test all methods, against the Ownera Test node.
Code samples can be found here:
The structure of the API includes 4 parts.
The first part of the API deals with profiles of identities:
- Creating Ownera users or “owners”
- Creating Ownera assets
- Defining entities that can attach claims to owners (“claim providers” – explained below).
The second part of the API deals with “claims”:
Claims are properties of an ownera profile, which are “given” to the profile by a trusted third party.
There are two major use cases for claims:
The first use case is to provide independent verification to an owner that it has certain qualities. For example, a KYC is a claim, a document that verifies that a user is an “Accredited Investor” is also a claim.
- Owners can have multiple claims, even of the same type. For example, a person can get a KYC certificate from Bank A (so they can to invest in an asset distributed by that bank), but may then require a separate KYC from Bank B to buy a different asset.
- The “claims” model replaces the “whitelist” model which many security token platform use. Instead of an asset saying which wallets can hold a token, the asset would specify which claims (from which providers) a user must hold in order to hold the asset's tokens.
- (A “whitelist” is a less-efficient subset of the claims model, which can be implemented using a “belongs to whitelist” claim issued by the asset owner. However whitelists are much less efficient, especially when dealing with secondary trading venues – it is much more efficient to define the rules for who can hold a token, and then enforce those rules at the transaction level, regardless where the transaction is initiated.)
The second use cases for Claims is to enable the KYA (Know your Asset) model of Ownera.
- KYA is a set of documents that describe the asset and the exact ownership rights of token holders (such as what happens in the event of an exit, or eligibility to receive dividends). KYA documents are legally binding (for example, scans of signed real-world ownership documents where needed), and adding them as claims to the asset makes them immutable on Ownera - so token holders have legal clarity of exactly what the tokens entitle them to.
- According to the Ownera model, only the primary node of each asset (or entities approved on its behalf) are allowed to add KYA documents to an asset. This means potential owners who wish to invest can always know what they are buying, and exactly who verified that information (i.e. a regulated financial node).
- Each asset on Ownera is expected to have a KYA claim.
The third part of the API deals with documents:
These APIs simply allow the upload of documents to support a specific claim. The documents are kept (for V1) on the blockchain itself, and may be encrypted by the claim provider for privacy.
The forth part of the API deals with the tokens representing the digital securities:
These APIs supports issuing new tokens for an asset, as well as executing transactions in which asset tokens are transferred between owners.
In future version there will be full API support for atomic swaps of tokens against any currency.