Mailmus

Roles and permissions

Decide what each person can do in your application, and ask Mailmus before acting.

Your server asks one question before it acts: can this person do this? Mailmus answers with a yes or a no, and says why.

It works the same whether you sign people in with Mailmus Auth or on your own.

How it fits together

  • A permission is something a person can do in your application, written resource:action, for example invoice:create.
  • A role groups permissions. It is given to a person, for your whole application (support, analyst, billing).
  • A person can have several roles. Their access is everything their roles allow together.

Declare your permissions and roles

const api = `https://api.mailmus.app/projects/${projectId}`;
const headers = { Authorization: `Bearer ${secretKey}`, "Content-Type": "application/json" };

await fetch(`${api}/access/permissions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ key: "invoice:create" }),
});

await fetch(`${api}/access/roles`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    key: "billing",
    name: "Billing",
    scope: "PROJECT",
    permissions: ["invoice:create"],
  }),
});

A role that is still given to someone cannot be deleted: remove it from those people first, so that nobody loses access without their session knowing.

Give roles

To a person, for your whole project:

// PUT /projects/{projectId}/customers/{id}/roles
// { "roles": ["support"] }

Changing someone's roles signs out their current Mailmus sessions, so their next token reflects the change.

Check access

const res = await fetch(`${api}/access/check`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    externalUserId: "user_8291",
    permission: "invoice:create",
  }),
});
const { allowed, reason, roles } = await res.json();

Identify the person with customerId or with your own externalUserId.

A refusal is a normal answer, not an error: allowed is false and reason tells you why. Add "explain": true to get each step of the decision.

To answer "why can't Sophie refund this invoice?" without writing code, open Check access in Auth → Roles & permissions, or use Explain on a Customer. The dashboard asks the same question your server does and shows each step of the answer.

reasonMeaning
PROJECT_ROLEAllowed by one of the person's project roles.
NO_ROLE_GRANTSNone of the roles considered includes this permission.
UNKNOWN_PERMISSIONThis permission was never declared in the project.
CUSTOMER_NOT_FOUNDNobody with this ID in the project.

In the session token

If you sign people in with Mailmus Auth, the token carries roles (the person's project roles). It is a snapshot taken when the token was issued: to decide on something that matters, use the access check.

Next

On this page