| Expand | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
...
Accesses
An access is an ID created to represent a relation between an application and a certain user via their role account or personal account. An access has separate keys which can sign transactions individually in order to create traceability for the application when a user acts in a role account or personal account.
| Expand | ||
|---|---|---|
| ||
If an organisation wants to interact with a user in another organisation than their own, they create an external role account for them, and if they want to interact with a natural person (an individual in their own capacity), they create an external personal account for them. This external role account or external personal account is then provided with an access to the application. There are two types of accesses: organisational (in the REST API named "corporate") and private. Organisational accesses are intended for B2B business-to-business relations via internal and external role accounts, whereas a private access is intended for B2C (business-to-consumer) or C2C (consumer-to-consumer) relations via external personal accounts. With their access, user accounts can participate in transactions via the application. |
CDI REST API
The REST API is a web service interface for letting an application communicate with the Lequinox platform. It is used for handling roles, user accounts, server accounts, accesses and transactions. This API can be used for everything from business-to-business interaction where your application is interacting with users from other organisations, to business-to-consumer or consumer-to-consumer interaction where your application creates platform-managed external personal accounts and can create transactions between role accounts and personal accounts in a variety of interactions.
| Expand | ||
|---|---|---|
| ||
Refer to the Lequinox platform CDI REST API to implement platform functionality and make your application Lequinox-enabled. You will find helpful pointers in our tutorials, and in the functions section. |
Lequinox-enabled applications
This refers to an application that is utilising Lequinox platform functionality.
| Expand | ||
|---|---|---|
| ||
An organisation that is connected to and exists on a Lequinox platform, utilising a Lequinox-enabled application, gains traceability for all their interactions with other organisations and users they add to their own application. To do this, they must incorporate Lequinox platform user types applicable for their use case. |
Lequinox global ID
Anything that needs to be found and located in the Lequinox platform environment is given a global ID. The ID can refer to a role, a role account, a personal account, or an access.
| Expand | ||
|---|---|---|
| ||
For an application developer, the global ID is the most important thing to keep track of – the ID is the key to finding other platforms, organisations, and users in a system of Lequinox platforms. |
Internal vs external
The internal and external concepts are applied to roles, role accounts and personal accounts (labelled "personal identities" in the REST API). Internal roles and internal role accounts are sometimes labelled proper roles and proper role accounts, in that they are more closely linked to the organisation. External roles and external role accounts are sometimes labelled substitute roles and substitute role accounts in that they exist in the absence of a proper role account in another Lequinox-validated organisation that the user would otherwise utilise via an access.
...
| Expand | ||
|---|---|---|
| ||
An organisation in the Lequinox platform is one that has chosen to be fully and officially validated in a Lequinox platform. The concept of external roles and role accounts makes it possible for this type of organisation to interact with companies and organisations that are not on a Lequinox platform. The organisation can trace their interactions with users inside as well as outside the organisation, that is, even users from organisations that are not on a Lequinox platform to begin with. Administrative functions relating to external user accounts can be managed via the Lequinox platform CDIServer API or the Lequinox console, by an administrator with access to the Lequinox console. Administrative functions relating to internal users are primarily managed via the Lequinox console. Account interaction with a Lequinox-enabled application and the platform, like creating, opening and signing transactions, is managed via the REST API. For more information on administrator functionality in the Lequinox console, see the Lequinox platform user guide. |
User accounts
In the platform, a user account can be represented in the form of an internal or external role account, an external personal account (in the REST API referred to as an external personal identity) or a server account. As such, a user account is either of the corporate, private or server type.
...
| Expand | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||
The four user account representations can have these types and ‘attributes’ in the REST API.
|
Role accounts
A role account identifies a user representing an organisation in the Lequinox platform. Behind it is a personal account (labelled a ‘personal identity’ in the REST API), which is linked to and works as an anchor for the role account. Please note that, despite its label in the API, the personal identity is not to be regarded as an ‘identity’ in the usual meaning of the word.
Internal role accounts
Internal role accounts are primarily intended for users within the application-owning organisation, like employees, with a certain mandate to administer and perform a set of actions within your organisation based on the agreements and authorisations tied to the account.
...
| Info |
|---|
Internal role accounts can only be created and updated via the Lequinox console, but information about them can be fetched via the REST API. |
External role accounts
External role accounts are primarily intended for users in organisations that are not activated on a Lequinox platform. They can be contractors, advisers and the like, which are hired but not employed by the Lequinox platform-validated organisation.
| Expand | ||
|---|---|---|
| ||
Creating external role accounts for users outside the organisation makes it possible for an organisation to interact with them and get traceability even if their company or organisation is not validated in a Lequinox platform. The organisation might want them to act under a certain policy so that they can trace their interactions with these third parties. External role accounts can be seen as substitute internal role accounts in the sense that they are created in the absence of a role account in another platform organisation. Contrary to internal role accounts, external role accounts can be created and updated via the REST API as well as the Lequinox console. |
Personal accounts
A personal account identifies a user that does not represent an organisation in the Lequinox platform, in other words, a natural person acting in their own capacity. Via their external personal account, they can participate in transactions and create, open and sign transactions in business-to-consumer or consumer-to-consumer interactions.
| Expand | ||
|---|---|---|
| ||
Creating external personal accounts for natural persons in their own capacity makes it possible for an organisation to interact with them and get traceability. External personal accounts can be created and updated via the REST API as well as the Lequinox console. |
Server accounts
In the Lequinox platform, a server account is an account representing the owner of a Lequinox-enabled application. Via the server account, the application – just as a role account – can be a participant in transactions and create, open and sign them. A server account should be used when you want traceability for events that are not related to the actions of a natural person, but an organisation or a machine or some other device.
...
| Info |
|---|
Several applications can use the same server account, but this is not recommended. |
Roles
In short, a role is a group of role accounts. They can be either internal or external.
...
| Info |
|---|
Internal roles can only be created and updated via the Lequinox console, but information about them can be fetched via the REST API. |
Internal roles
Internal roles are intended for role accounts (users), in your own platform organisation, like employees.
| Expand | ||
|---|---|---|
| ||
Only internal role accounts can be assigned to an internal role. Internal roles are sometimes referred to as ‘proper roles’, to be contrasted to external roles being referred to as substitute roles (as in substitutes in the absence of a proper role in another organisation). |
External roles
External roles are intended for users outside your own organisation that is fully and officially activated in a Lequinox platform. These external users can be contractors, advisers and the like, which are hired but not employed by your Lequinox platform-validated organisation.
| Expand | ||
|---|---|---|
| ||
External roles can be seen as substitute roles in the sense that they are created in the absence of an internal (proper) role in another platform organisation that the would-be user would have been assigned if their organisation was validated on another Lequinox platform. Contrary to internal roles, external roles can be created and updated via the REST API as well as the Lequinox console. |
Transactions
| Info |
|---|
The term transactions does not refer to financial transactions, but traceable transfers of data with integrity intact. |
Definition of a transaction
The Lequinox platform allows users to create, send and open encrypted transactions via Lequinox-enabled applications. Transactions also include a number of services that determine what a participant can do with a transaction, and when.
| Expand | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
A transaction consists of a subject, body content and attachments. It also includes information about the participants of the transaction, that is, the creator and recipients. Via the platform REST API, the application can let the transaction creator decide which services should be activated or not for a transaction and, when applicable, which values should apply. The services available include the ability to see whether a participant has opened or signed a transaction; allowing all participants of a transaction to sign it; the ability to revoke a participant's access to a transaction (as long as they have not yet opened it); and the ability to lock a transaction before or after a certain point in time. Transactions can be created in machine-to-machine interaction via a Lequinox-enabled application where the application server account is the participant, acting for the user accounts that utilise the application via their access. To participate in a transaction, they each need to be provided with an access to the Lequinox-enabled application that provides this functionality. Examples
Transactions within organisations
Internal role account in Organisation A ↔ internal role account in Organisation AThey can both have internal role accounts at Organisation A. Their internal role accounts can only be created via the Lequinox console, although a Lequinox-enabled application can fetch information about these role accounts via the platform API. John's transaction can either be created with him as a platform-managed user, or the application can be set as the creator and send the transaction on his behalf.
Internal role account in Organisation A ↔ external role account in Organisation AJohn has a platform-managed internal role account and an application access in Organisation A. Via their application, Organisation A has provided Jane Dough with an external role account and an application access. John's transaction can either be created with him as a platform-managed user, or the application can be set as the creator and on his behalf send the transaction to Jane Dough's external role account. Transactions between applications (server accounts)
Application server account ↔ application server accountFor transactions directly between applications, their server accounts will be creator and participant respectively. |
The transaction archive and traceability
The archive offers traceability for organisations that have a Lequinox-enabled application registered to their platform organisation.
| Expand | ||
|---|---|---|
| ||
When a transaction is created or acted on, the platform always archives the transaction ID along with metadata on who participated, who opened, who signed and when. For internal role accounts and server accounts, the transaction and its content is encrypted and a transaction event is archived on behalf of the internal role account or server account and can be opened on the behalf of these two accounts. If you want to track content for external role accounts and external personal identities, this service needs to be implemented in your Lequinox-enabled application. Your application cannot open platform transaction files directly, but via the REST API, it can ask the platform to open them on its behalf if your application (via its server account in the platform) was a participant in the transaction and hence is authorised to make this request.
|
User agreements
In the Lequinox platform, user agreements apply to the use of applications and roles.
Application user agreements
Any application that an organisation wants to assign to a Lequinox-enabled application requires an application user agreement.
| Expand | ||
|---|---|---|
| ||
Application user agreements are created by an organisation manager via the Lequinox console but cannot be created via the REST API. When the application is set up, the user agreement must be assigned to the user group that is to be connected to the application. |
User groups
All applications must belong to at least one user group, which determines the user agreement that applies when the role accounts with access to that group utilise an application.
...