Authentication answers who is calling. The profile you select answers where you are working and with what rights. Exowpee keeps the two apart on purpose, so that one person can run a shop, follow a client account and administer an organization without the three getting mixed.

​
Six account types

Every account has a type, which decides the space it works in. The type is the {type} in sign in. The body always uses the field username, which the server lowercases. Members send their email in it; agent accounts send their username. Sign-in is limited to five attempts per minute. Wrong credentials and a deactivated account give the same refusal. Members must have verified their email first; an unverified email gets its own error. An agent account is an employee login, not an automation. It is created by someone allowed to manage agents, has a username instead of an email address, no membership, and works under one fixed custom profile. Comlan, the trainee of Cabinet Hounkpatin, has an agent account. See manage agent accounts.

​
Members choose a profile after signing in

A member is one identity shared by all spaces, with one password. Signing in as a member does not choose a space. The token you get is an identity session: it carries no company, no profile and no permissions. An identity session reaches only a few routes: who am I, my permissions, refresh, sign out, change password, update my account details, check for data refresh and the switch routes. Anything else answers 403 until a profile is selected. The application then shows the member’s active profile assignments and asks them to pick one, or uses the one marked as default. Choosing means calling the switch route of the space: The call sends the id of the assignment, not of the profile. It is refused with 403 when the assignment is not the caller’s, is inactive, or points to a space of another kind, when the membership is inactive, or when the company or client account is deactivated. On success the server returns a new token scoped to the owner and profile, and the previous token of that space stops working. A person has at most one default assignment per kind of space: one for companies, one for client accounts, one for the organization. Setting a default does not sign anyone into it. See assign access to people. An agent account has nothing to choose. At sign-in the server reads its owner and its profile and issues a scoped token directly. An agent account cannot switch.

​
One session per account and space

Each member has three independent sessions, one for the company space, one for the client space and one for the organization space. An agent account has one. Each session is a random key stored on the server as a hash.
  • Signing in, switching profile or refreshing replaces the key of that space. Every older token of the same account in the same space stops working, on every device. Signing in on a second device therefore signs out the first.
  • Signing out clears the key of the current space.
  • Changing or resetting the password clears all three keys of the member.
  • Sessions of the other spaces are not touched by a sign-in, a switch or a sign-out.
The token carries the random key, not its hash. Each protected request compares the key with the stored hash. A token with a valid signature but a revoked key answers 401.
Because a switch replaces the session of its space, a person who switches from the Akpakpa shop to the Abomey-Calavi shop leaves no way to keep both open at once with the same account. The application must keep one token per space.

​
What the token proves

A scoped token identifies the account type, the organization, the owner of the space (company, client or organization), the selected profile and, for members, the assignment that was chosen. It is not trusted alone. On every request the server also checks that:
  • the session key is still the current one;
  • the account is active;
  • the company or client account is active;
  • for a member, the assignment is active, belongs to that owner and organization, and the membership is active;
  • for an agent account, its profile still exists and its owner and organization still match.
A member or agent account whose company or client account is deactivated is refused on their next call, even with an unexpired token. Deactivating an agent account also revokes its session.

​
What authentication does not decide

Authentication does not grant rights. After it, each action checks the profile’s permissions in the selected space. Read permissions explained. Which routes a session may reach also depends on its space: an organization session cannot call company routes and the other way round, and agent accounts cannot call routes that manage access. A token is bound to its account type, so such a call answers 401.

​
What the application must do

  • Keep one token per space and replace it after every sign-in, switch and refresh.
  • Clear everything shown from the previous space after a switch.
  • Treat 401 as a revoked or expired session, or a token used on a route of another space, and ask the person to sign in again to the right space.
  • Treat 403 after sign-in as a missing profile selection or a missing right.
  • Use refresh to stay signed in; it returns a new token with the same profile and revokes the old one.
Refusals come in a few shapes. A missing, revoked or inactive session, or a token sent to a route of another space or kind of account, is 401. A profile that is not selected or a switch that is refused is 403 with status_code and message. A validation error is 422 with message set to Validation error and an errors object. A refusal by a business rule is 422 with a message. An unverified email is 401 with error_code set to email_not_verified.