Accounts, roles and subscriptions
Functionality and permissions are centered around the notion of accounts. The application recognizes three types of accounts:
- user accounts
- A user represents a individual (or bot) with login credentials. Technically a user, after authentication, holds a session token that is passed to the server on each HTTP request. Users call API end points, and hold permissions to do so, through roles on organization and personal profiles.
- billing profiles
- A billing, sometimes called an organization profile, has no login credentials. It typically represents a legal entity that can be charged for service. Users can operate on billing profiles (ex: subscribe the organization to a plan) though roles they hold on an billing profile.
- personal profiles
- A personal profile is very much an aggregate of a user account and a billing profile into a single profile. It can behave as either. Personal profiles should exclusively represent a natural person as defined by the General Data Protection Regulation (GDPR). Enforcing this restriction is useful to maintain compliance.
- A typical consumer product will prevent third-party users to have a role on a personal profile, enforcing a one-to-one relationship between a login and an account. This is not a requirement. In some cases, like educational sites, it is often useful to grant a parent (personal profile) a specified role to the personal profile of their children.
Billing profiles can act as various parties of a subscription relationship.
- provider profiles
- A provider, sometimes called merchant account, provide subscription plans other billing profiles can subscribe to.
- subscriber profiles
- A subscriber is typically allowed to use a product under the condition they have an active subscription.
- broker profile
- A broker is a special kind of provider that represents the hosting site itself. Thus there can only be one broker per site domain. Typically a user with a manager role on a broker is allowed to change the color theme, notification e-mail templates, etc.
There are no pre-condition that certain profiles are providers while others are subscribers. In fact some profiles can be both subscriber and provider depending on the relationship under discussion.
As an example, a typical substantiation for a sports club might look like:
Accounts contain information to:
- uniquely identify the account
- The slug field (aliased to username for users) is specifically crafted to be used in URL paths. Using an account slug, it is possible to get details on the account by calling the Retrieve Account Detail API.
- display a human-readable name
- The fields full_name is a human-readable name for the account. Alternatively printable_name will either be the full_name or default to the slug when full_name is empty. It is recommended to use printable_name is the user interface (UI) when a human-readable needs to be displayed.
- contact the account
- The fields e-mail and phone are available for that purpose.
In addition profiles contain fields:
- for billing purposes
- street_address, locality, region, postal_code, country and a payment method on file available through the Retrieves a payment method API.
- to list subscriptions
- Active and past subscriptions are available through the list subscriptions API.
All accounts have an extra text field which can be used to store application specific information, JSON-formatted for example.
A role is a relationship between a user and a billing or personal profile - shorten to profile later on - that grant the user certain permissions to act on the profile. Permissions are not directly tied to the Role object, but rather to an abstract representation of the role called a RoleDescription.
It is not uncommon in casual conversation to use role to mean RoleDescription when talking about permissions as the end result is about the same. None-the-less, the workflows involved to grant a role to a user, such as opt-ins and double opt-ins can only be set on the RoleDescription, affecting all role objects using that RoleDescription.
Profile-restricted role descriptions
It is possible to create profile-restricted RoleDescription objects (API). These roles will only appear in the dashboard for that specific profile.
Whereas RoleDescription objects with are not associated to a specific profile can be used to grant any user the role described to any profile, profile-restricted roles can only be used to grant users that role on the specified profile.
As shown on the example below, the teacher role cannot be associated to grant Jane a teacher role on L.A. Wing Chun School as there are no such RoleDescription in the global site domain or the local L.A. Wing Chun School domain. The teacher role belongs to L.A. Taekwondo School exclusively.