Documentation

What is Integrity?

This guide is aimed at users, businesses or developers who want to quickly grasp the key concepts of the Integrity Platform, and its specificity.

Overview

Integrity is a decentralized identity platform that enables simple and secure exchange of personal data attributes (Facts). No central authority is needed so the user can always keep his information private and under control. Integrity is built on the Brickchain identity protocol.

The Integrity platform is made of three main elements:

1. The Integrity Mobile App (iOS & Android) is a digital wallet to store and manage personal data in a secure environment. The user must give his consent if information needs to be shared with a service. No central repository is used: the phone becomes a decentralized data wallet.
2. The Realms can be accessed through the Integrity App. They are created and managed by organizations who want to share something (a service, a resource, a website…). This is what the user connects to: it’s a very thin layer of functions that manages relations to services through roles and permissions (Mandates).
3. The Integrity Services are made available to Realm owners as out-of-the-box features. Thanks to our developer community, the number of services is growing everyday. For any project or request, please get in touch via hello@integrity.app.

The Integrity Mobile App

The Integrity Mobile App turns smartphones into secure data wallets. It is the place where all the decentralized identity components interact.

On the Integrity platform, identities are composed of data stored only in the user’s phone which is protected by our strong encryption software.

How the user regains sovereignty on his data

When a user first installs the Integrity app, a set of asymmetric keys is created. The public part corresponds to the root User ID (UID): it represents the user as an entity throughout the system. Subkeys can then be generated to create some identities.

This architecture ensures privacy across the whole platform and removes the need for any central authority other than the user himself. This means that transactions happen on a one-to-one basis without requiring any intermediary. The user manages his identities without relying on a third-party that captures all his personal data for undefined commercial purposes, along with high security risks.

The user generates reliable identities, based on Facts

A public user ID is often considered insufficient for a third party to trust a user. Many services require some validated facts (or data attributes) such as e-mail addresses, phone numbers, social media accounts, passports or national eIDs. These facts may be shared directly with a service that may need them to provide the functions you need.

Thanks to Integrity, facts can be anonymized by a proxy such as a zero knowledge service, in order to protect any personal identifier.

For example, the Integrity App can be used to pursue a basic ID check such as age verification. In an anonymization process, the user will transmit only one fact: the status of having attained the age of majority. Critical data such as the name, address or even birth date stay private: the nightclub, alcohol shop or adult website, will not have access to it.

A Fact can be a data attribute of any kind

A Fact may consist of ephemeral data such as a geolocation, a coupon or a timestamp. But a Know Your Customer (KYC) service offered by a trusted realm can also be used to issue certified facts.

Any of these data attributes are then stored locally in the phone, where the user can leverage the eventual certified facts to redistribute trust.

When a service or realm requests facts as part of a transaction, these can be shared in one click, but only if the user gives his consent.

If the user has many facts of the same type, such as multiple e-mail addresses, the user selects which one to share with the service.

Roles & Permissions are managed through Mandates

In order to perform an action with a service from the Integrity App, the user needs a mandate that grants him the permission(s) to do so. Mandates are provided by the realm offering the service.

An action contains a signed action document that also wraps the mandate - the mandate is signed by the realm and the action is signed by the user. In this way, the service controller can validate the signatures over the action and the mandate, and follow the signatures back to the issuing realm.

Facts may also be needed along with the mandate to perform an action. The user can choose which facts to share with the service.

In any case, the action is executed only if it is validated according to the service policy.

The user gets Receipts & new Mandates

Last but not least: Actions produce Receipts that are stored in the user’s logbook. Along with a receipt for performing an action, the user could also receive a number of new mandates that unlock access to other services. These receipts could be signed agreements, room bookings, or facts of ownership with links to related services.

When facts are shared with a service, the operation is also sent to the logbook in the app, so that the user can always keep track of his personal data.

The Realms

Joining a Realm

Users can join a realm when a mandate is delivered to them: this operation grants them a certain role for a specific organization.

For example, users may get an invite from someone who wants to share a resource with them: meeting room access within a co-working space, control of a connected device in an automated home, etc.

The invite contains a link, which prompts the user to install or open the Integrity app. When starting it for the first time, the user is walked through a brief onboarding process. In case a backup needs to be restored, a new identity is created (as a set of cryptographic keys).

If the process is triggered by an external action, such as someone giving the user a mandate, the app immediately updates the status of the profile.

Providing specific identities to the Realm

A realm can require some information from the user, in order to authorize him to join or receive mandates.

Of course, the user can add some facts from the app: name, email, address, etc. But in order to certify these data attributes, an integrated KYC service could be used.

Once some facts are certified, they can be shared with a realm for identity verification. The Integrity platform provides high granularity as the user can share his data attributes one by one.

As explained previously, if a realm needs just one fact about the age, the user can remain anonynous by sharing his certified birth date without any other piece of information.

The authenticity of the facts is guaranteed via a chain of trust: . Our distributed identity architecture is both secure and flexible.

Using the Realms to manage roles & permissions

The mandate delivered by the realm gives the user the ability to act in a specific role, such as Admin, Employee, Staff, Guest or VIP. The mandate can also be even more specific, such as giving the user access to only one or few actions for a very explicit purpose, and for a limited time or during certain period intervals.

The naming and meaning of a role is dynamic, and the realm is free to use any naming scheme. Depending on the configuration, a service may choose to handle the roles in different ways, by giving access just to certain roles, or by offering discounts on certain services.

When the signup is done, the user will have access to the Integrity realm, where it is possible to create a new realm. If the invitation came from a service or another realm, the user should have received a mandate for that realm and be able to start using those services as well.

All realms the user is associated with is listed in the Integrity app.

The Integrity services

Services can be added to the Integrity platform in order to leverage the benefits of decentralized identity management, such as privacy focused roles and permissions systems or granular facts certifications.

For example, a home automation platform can rely on Integrity to manage multi-users: an Airbnb host can use our app and dashboards to manage his guests permissions (e.g. the door can be opened at a certain time and the heating can be regulated, but not pushed to its maximum capacity).

Compatibility with OAuth2, OpenID and SAML ensures interoperability between Integrity and the Identity Providers (IdP) ecosystem.

Services are integrated in minutes within the Integrity app, with extended branding and experiences options for smooth user flows.

Librairies are available and SDKs are being developed: please get in touch for any specific demand or suggestion: hello@integrity.app

The remote control for your environment

The Integrity app is an interface for accessing services that can be mapped to any action. A list of services available to the user can be displayed within each joined realm. But beyond that, the user may discover services through different means: * Geolocation to find and browse nearby realms; * Local network announcements such as mDNS broadcasts; * URLs on a web page, in an email or through bots in a messaging channel (Slack, etc.); * QR codes or NFC tags that may be displayed in specific places, such as a meeting room door for reservation management.

NOTE: Some of these features are still under development. Please get in touch via hello@integrity.app for more details.

Any of these App interactions triggers a service that creates the correct action to manage the object.

Services are exposed via a Controller triggered by an Action Descriptor

For example, a calendar with booking options (= service) can be displayed if a QR code scan (= action descriptor) opens the Integrity App and loads the resquested user interface from the controller.

This user interface can be hosted anywhere, but from a user standpoint it behaves as if it is natively embedded in the Integrity App.

A Controller can offer any type of service: * Transaction on a marketplace * Interaction with an IoT device * Certifications by a KYC service * Control of a vending machine * Etc

Once all the parameters have been provided, the user can trigger the desired action from the app. All the data is then sent to the controller endpoint for validation, so that the action can be performed.

Realms grant Mandates for roles & permissions within the services

As explained in Joining a realm, access requirements are specific and defined by the realm owner. The range of options varies from accepting self-registered “guests” to asking for KYC verified and gov ID certificates. Access may also be granted through the signing of contracts.

Therefore, based on the parameters that have been provided, the user receives a mandate that grants him specific roles and permissions.

For example, when validated, such an action might unlock access to an IoT admin panel, or grant a permission for managing a connected object such as a frontdoor lock. Please see our Home Assistant integration if you need to picture all the possibilities of such a setup.