👩💼Users, Logins, and Accounts
How end-users use and access Plannr
Introduction
It is imperative to understand the difference between Users, Accounts and Logins within the context of Plannr, as they are all separate models that work in conjunction with each other. This section aims to explain the structure of the Accounts system.
Models
Users
The User model represents an end-user on a Firm in Plannr. A User has their own details, like an email address, password, and name. The email address and password on a User model are always what an end-user logs in to Plannr with, even if they have multiple different logins across different Firms.
Logins
A Login is the middleman between a User and an Account. Logins store permissions and are related to both an Account and a User - a Login can only belong to one of each in a One to One relationships. Users can have many logins for different Accounts and Accounts themselves can also have many logins which would correspond to different users.
Accounts
An Account is where the information representing a person or entity on a Firm is contained. This includes details like the Account type (client, employee etc.). Accounts can have many Logins which can allow various different Users to use that Account.
For example, a Joint account representing two people may have a Login for each participant, which in turn would correspond to different Users. If an Account with an email address has a Login created for it, an email is sent to that address if the Login does not match an existing user. This email prompts an end-user to register - creating a new associated User model. Otherwise, if a User with the same email address already exists upon creation, the Login will be associated to that User.
Accounts also have types and roles which represent various financial entities within a Firm. In the context of Employees, there is a hierarchy of increasing permissions with the highest being Owner and lowest being a Member. This table explains which types correspond to which role:
Structure and Relationships
Let's start with a diagram that shows a good example of two different Users with multiple Logins and Accounts:
There are a few key rules and relationships that can be learned here:
Users can have many Logins (HasMany)
Accounts can have many Logins (HasMany)
Logins belong to only one Account and one User (OneToOne)
Users can have Logins that correspond to Accounts on differing Firms
Different Users can access the same Account as long as they have a Login for it
API Perspective
Let's examine this structure from a perspective of a developer consuming the API - this is important as there are a few key considerations.
Logins Endpoint
First is an important endpoint that isn't currently listed in the API Documentation:
https://api.plannrcrm.com/api/v1/logins
This route will list all logins and there are no other headers required, you just have to pass the Bearer Token for access.
Initial Setup
Currently, a Firm cannot be setup via the API, so it will always have at least one initial User with a Login and Account.
When creating and authenticating a User for the first time make an API call to the endpoint listed above. It is recommended when building an integration for the Plannr API to take the first login from the response and access the related Account to get the UUID. As mentioned in the Making Requests section, the X-PLANNR-ACCOUNT-UUID is always required for every other endpoint as the API is stateless!
Implementation Tips
If a User has multiple logins, it is recommended to implement a selector for each login - like the Account Selector built into Plannr CRM. This way, Users can easily switch between Accounts and select what Login they would like to use. This is aided by having <X MODEL> having the ability to be marked as primary via the API.
If you are building an integration that is adviser-facing then a recommended action is to filter out logins where the account type is not 'employee'. This aids in preventing issues where an Account is accessed by two end-users at the same time.
Last updated
