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 exampleinvoice: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.
reason | Meaning |
|---|---|
PROJECT_ROLE | Allowed by one of the person's project roles. |
NO_ROLE_GRANTS | None of the roles considered includes this permission. |
UNKNOWN_PERMISSION | This permission was never declared in the project. |
CUSTOMER_NOT_FOUND | Nobody 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
- Verify sessions
- Webhooks:
access_role.*,access_permission.*andcustomer.roles_updated.