Accounts

An account is the unit that owns data and receives mail on the server. Everything a user keeps on Stalwart belongs to an account: its email address, its mailboxes, calendars, address books and files, and its storage quota. The account also carries the permissions that decide what it may do. Understanding accounts is therefore the starting point for most administrative tasks, from adding a user to setting up a shared mailbox.

Accounts come in two kinds:

• A user account represents a person, or a service, that signs in. It holds the credentials needed to do so.
• A group account represents a shared mailbox and a set of shared resources. The members of the group reach them through their own accounts. A group has no credentials and cannot sign in.

Both kinds are variants of the Account object (found in the WebUI under Management › Directory › Groups, Management › Directory › Accounts). The @type value tells them apart: User or Group. User accounts and Group accounts describe the fields of each, and Managing accounts gives the procedures for creating, changing, suspending and deleting them.

Addresses and aliases

Every account has a primary address, built from two fields. name is the local part, the text before the @. domainId refers to a domain hosted on the server. The server derives the read-only emailAddress field from these two values. The account named jane in the domain example.com therefore receives mail for [email protected], and signs in with that address.

An account can receive mail at further addresses through aliases. Each alias has its own local part and domain. It also has an enable flag, which turns the alias off without removing it.

An address belongs to exactly one account, group or mailing list. Two accounts therefore cannot share an address. An address that must reach several people belongs instead to a group, which shares one mailbox, or to a mailing list, which forwards each message to its members. Addresses, aliases and catch-all describes how the server resolves recipient addresses.

Credentials

A user account signs in with one of the credentials stored in its credentials list:

• A password, the primary credential, which may also carry a two-factor authentication secret (Passwords, Two-factor authentication).
• App passwords, separate passwords for individual applications, each with its own expiry, address restrictions and permissions.
• API keys, bearer credentials for scripts and services.

App passwords and API keys are secondary credentials. They are created after the account exists, and their secret is generated by the server and shown only once.

OAuth applications do not appear in this list. Each application the user has authorized is recorded instead as a separate grant, which the user can review and revoke. Request authentication explains which credential each protocol accepts.

Group membership

Membership is recorded on the user, not on the group. The user’s memberGroupIds field lists the groups the user belongs to, and a group does not list its members. Groups cannot be members of other groups.

Membership gives a user access to two things. The first is the group’s own data, such as its mailboxes. The second is everything that has been shared with the group, so sharing a calendar with a group shares it with all of its members.

Membership does not pass the group’s roles or permissions to its members. A group’s permissions govern only what the group account itself may do, for example whether it may receive mail.

Roles, permissions and quotas

What an account may do is decided by its roles and its permissions. A role is a named set of permissions, defined once and assigned to many accounts. Two fields of the account control the result:

• roles selects the default User or Administrator roles, or a custom list of roles.
• permissions adds or removes individual permissions on top of the roles.

Authorization describes the model, Roles the default roles, and Permissions how the effective permissions are computed.

Quotas limit how much an account may store. The quotas field limits the disk space and the number of objects of each kind that the account may hold, and the server-set usedDiskQuota reports the space in use. Quotas describes how the limits are enforced.

Two further fields connect the account to other systems. In the Enterprise edition, memberTenantId places the account in a tenant, an organisation hosted on the server. Membership restricts the account’s permissions to those the tenant allows, and makes the account visible to the tenant’s administrators. The externalId field holds the identifier that a SCIM identity provider assigned to the account.

Accounts from external directories

A domain can take its accounts from an LDAP, SQL or OpenID Connect directory instead of managing them on the server. The server still needs a local account for each user, because mailboxes and settings live on the server. It creates that account the first time the directory returns it. This happens at sign-in or, for LDAP and SQL, when mail arrives for the address.

Responsibility is then divided between the two systems. The directory supplies the password check, the display name, the aliases and the group memberships. Roles, permissions, quotas and every other field remain local to the server.

In this model the server creates accounts as it needs them. SCIM provisioning works the other way: the identity provider creates and deletes the accounts itself. Provisioning models compares the two.

Accounts in JMAP

JMAP clients see accounts as principals. A principal is the object through which JMAP Sharing (RFC 9670) lets users find each other and share data. Only user and group accounts are principals, of type individual and group respectively. Tenants, roles, domains, mailing lists, API keys and OAuth clients are separate configuration objects, so they do not appear as principals.