Copy of Concepts

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.

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.

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.

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.

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.

The four user account representations can have these types and ‘attributes’ in the REST API.

An internal role account is official, a starting point representing a certain role assigned to a user in an organisation that has chosen to be fully and officially activated in a Lequinox platform.

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.

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.

The server account is the actor when an application is to create, open or sign a transaction as the application itself. The application server account is not involved when creating, opening or signing transactions as any of the other platform-managed accounts. But the application API key authorises the application to act on behalf of platform-managed internal and external role accounts that have access to the application.

When an application is set up in a Lequinox platform organisation, it is also connected to a user group. When the application creates an access, the user group determines which agreement the accesses have to sign. User groups and agreements are set up via the Lequinox console by a Lequinox platform organisation administrator.

A role consists of role accounts that have been assigned that role, that is, when a user is assigned a role, what happens is that their role account is linked to – or included in – that group of role accounts. 

If a role is internal, that is, within the role-issuing organisation, the role also comes with a certain administration level in the Lequinox console. But in affect, the role is just a means for putting role accounts in a group.

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 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.

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 A

They 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 A

John 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 account

For transactions directly between applications, their server accounts will be creator and participant respectively.

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.

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 are created and updated by an organisation manager via the Lequinox console.