Not everyone in a shop should do everything. Sènami, the cashier, runs the register. Rodrigue, the seller, takes orders. Bio, the storekeeper, handles stock. Madame Illa, the owner, can do all of it. Exowpee answers “may this person do this here?” with permissions grouped into roles, roles grouped into profiles, and profiles given to people.

​
The chain

  • Permission: the right to perform one named action, such as products.create or roles.list. Permissions cannot be created through the API: they are listed by the permissions route of each space. Each one can be held only by certain kinds of account.
  • Role: a named set of permissions.
  • Profile: a named set of roles, belonging to one organization, company or client. A custom profile can be used by people and by agents, and each account receives only the permissions that exist for its kind.
  • Profile assignment: the link between a person and a profile in one space. A person may hold several, in the same space or in different ones, and selects one when they sign in (see authentication explained). An assignment may carry working hours.
An agent has no assignment and no choice. It has one profile, fixed when it is created. The first person of each space receives two built-in profiles named administrator and read only, with a role of the same name. Built-in profiles and roles are copied into each space, cannot be modified or deleted, and are for people only: an agent must use a custom profile. Anything else is custom. You build your own roles and profiles with define access profiles and roles, and give them to people with assign access to people. Management of access is reserved to people in every space. Agents have no route to manage roles, profiles, assignments, extra permissions or access grants, so an agent can neither raise its own rights nor those of anyone else.

​
A permission is checked in one space

Roles and profiles belong to a space. Sènami may hold a Cashier profile at the Akpakpa shop and a Manager profile at the Abomey-Calavi shop. The rights she has depend on the profile she selected, and change when she switches. See multi-tenancy explained. To see what the current session may do, call my permissions. It returns the permissions given by the selected profile plus the extra permissions of the person, for the kind of account. With no profile selected, it returns only the extra permissions.

​
Extra permissions

Sometimes a profile is almost right. Bio normally has the storekeeper profile, but this week he also prepares orders. Instead of building a new profile, Madame Illa gives him individual extra permissions, optionally until a date: grant extra permissions to a member, and the same for agents.
  • Extra permissions are checked together with the profile’s: a person may do an action if the profile or an extra permission allows it.
  • An extra permission with an expiry date stops counting when the date passes; nothing needs to be removed.
  • Each call replaces the whole set the person holds in that space. A permission left out of the list is removed, and an empty list removes them all.
  • At most five permissions can be sent in one call, each must exist for the person’s kind of account, and the expiry must be in the future.
  • It changes nothing about the person’s profile assignments.
See grant individual extra permissions.

​
Rules that apply to every action

These rules hold for every action. The pages of the actions do not repeat them.
  • A permission is needed. Each action shows the permission it requires. A member may do it when their profile or an extra permission holds it.
  • An inactive account is refused. A member or agent account that has been deactivated can do nothing.
  • A space must be selected. A member works in a company, a client account or the organization, after choosing a profile there. See multi-tenancy explained.
  • Working hours are respected. See below.

​
Working hours

An assignment, an agent account and a company can each carry working hours. A person with working hours is refused outside them; in a company session the company’s hours apply as well. Hours use the time zone of the company settings when there are any, and UTC otherwise, which is always the case in client and organization sessions. They are set on profile assignments and on agent accounts.

​
Administrators

An administrator has every permission. A member whose selected profile is the built-in administrator profile does not need each permission to be listed, and is not limited by working hours. Madame Illa, an administrator at Akpakpa, can create custom profiles there without being listed in any role.

​
Access to accounting books

Accounting follows a second dimension. Permissions say which accounting actions someone may do (record entries, close a year). Access grants say on whose books they may do it. Accounting works on one book at a time. The books of the organization and of its companies are reached from the organization space, with the book named in the URL under /v1/accounting/organization/books/{book}. A client account keeps its own books, reached only from its own client space under /v1/accounting/client, where no grant applies. Company sessions reach no books, journals, entries or reports; they keep only the routes for their own cheques, settlements and payment sources. An organization whose plan does not include the accounting module is refused on every accounting route.
  • A member or organization agent account can work on a book only if a grant allows it, unless they are an administrator. A grant links one actor, one domain (accounting is the only one today) and one target: the organization itself or one company. One grant per target.
  • A new company is open to the administrators of the organization only, until someone grants it to others.
  • Grants are managed by people, in the organization space, with grant accounting access, list access grants and revoke accounting access. Up to 100 targets can be granted or revoked in one call, and granting a target twice is refused.
  • Grants follow their actor: deleting the profile assignment or the agent removes its grants.
  • Reports that add several books use only the books the person may access. An aggregation adds them up; a consolidation, which removes flows between group members, covers the organization and all its companies.
Groupe Gbaguidi works this way: Mahougnon, the group’s accountant, receives a grant on the books of the organization and of the Parakou company, and sees no other company’s books. See limit access to locations and books and close the month with your accountant.

​
For developers

  • Check permissions for the actor’s own guard and selected profile through the shared helper userHasPermissionTo(), which also counts extra permissions. Checking only the profile misses extra permissions; checking only the user misses profile roles.
  • Authorization lives in policies, not in form requests. Form requests check the shape of the payload.
  • Some actions are not permission-driven. For example, creating an order or confirming a sale in the Order package depends on the person being a seller or cashier in the current context, not on an orders.create permission. See sellers and cashiers.

​
Where to go next