Every call except sign-in, sign-up and password recovery carries a session token:
A token is a signed JWT, but it is not enough on its own. On every protected call the server also compares the session key inside the token with the one stored for the account, and checks that the account, its profile, its membership and the company, client account or organization it works in are still active. A token that was valid a minute ago can therefore be refused after a new sign-in, a sign-out or a deactivation. This page is for the developer who builds a client. The business view, with the people who do these steps in a shop, is in Sign up and sign in and Your account and notifications. The ideas behind it are in Authentication explained.

​
Pick the kind of account

Exowpee has three spaces: a company, an organization and a client account. Each has members and agent accounts, which gives six kinds of account. The kind is the {type} of the sign-in URL, POST /v1/auth/{type}/login. A route with any other type does not exist. A member signs in with the email address in username and a password. An agent account signs in with its own username and password, and names its owner with the field of the table. The owner field is required for agent types and refused for the other types. One member has one email and one password, but a session in each space. Working in a company does not sign you in to a client account.

​
Sign in

Sign in answers 200 with auth.access_token, auth.token_type (bearer) and auth.expires_in in seconds. By default a token lives 7 days; the deployment can change it. The answer also carries the account in user, with is_seller and is_cashier. What differs between a member and an agent account:
  • A member gets a token with no profile selected. user.user_profiles lists the profiles the member can work with in this space. A token without a profile can only reach its own account (view, edit, permissions, password), refresh, sign-out, the refresh state and the profile switch; every other route answers 403 until a profile is selected.
  • An agent account gets a token that already carries its profile, owner and organization. It cannot switch.
  • A member must have verified their email. Otherwise the answer is 401 with error_code email_not_verified.
Sign-in is limited to 5 attempts per minute on the route. Wrong credentials and a deactivated account get the same 401, so the answer does not reveal which one it is. An agent account is also refused when its company, client account or organization is not active, or when its profile no longer exists.

​
Select a profile

After sign-in, a member chooses where to work. Use a profile marked is_default in user.user_profiles when there is one, or let the member choose. Then call the switch action of the space, with the id of the chosen assignment: The answer has the same shape as sign-in. Replace the stored token with the new one. A member who has several companies uses the same action to move from one to another, and gets a new token each time. A switch is refused with 403 when the assignment is not the caller’s, is inactive, belongs to another kind of space, when its profile no longer belongs to that owner, or when the membership or the owner is no longer active. Only members can switch; an agent account token is refused with 401.

​
Keep the session alive

Renew my session gives a new token with the same selected profile and the same lifetime rule, and stops the token used for the call. Call it before expires_in runs out, and store the new token. Renewing also stops older tokens of the same account in the same space. View my account shows who is signed in. List my permissions shows what the current profile allows, which helps a client show or hide buttons. How these permissions are decided is in Roles and permissions.

​
Sessions and spaces

The server stores one session key per account and per kind of space (company, client account, organization). This explains most surprises:
  • Signing in again, switching profile or renewing makes a new key. The tokens that carried the old key of that account in that space stop working, on every device. The holder of the old token sees 401 with the message “You have been signed out because a new login was initiated from another device.”
  • A switch in one space does not touch the sessions of the other spaces. Sign-in as an agent affects only that agent.
  • Sign out clears the key of the account in the current space, so every token of that account in that space stops, not only the one used for the call. It answers 204.
  • Resetting a password with Reset my password, or changing it with Change my password, stops the sessions of the member in every space. The member must then sign in again everywhere.
  • A token with no session key, or with a key that does not match, is refused with 401, with no exception for older tokens.

​
Errors you will see

These are the answers a client can meet. On 401, drop the token and sign in again. On 403 because no profile is selected, call the switch action of the space.

​
Where to go next