Mautic roles and permissions setup

Mautic roles and permissions: keeping marketers, sales and agencies in their lane

If your self-hosted Mautic team currently gives every new account full administrator access, you are carrying more risk than the work requires. Mautic controls access by associating user accounts with roles, and each role allows or denies access to features. Roles are managed under Settings, then Roles. The default behavior is the problem: Mautic creates new users with the Administrator role and full system access. Changing that default is a configuration decision your team should make deliberately, not something to leave until the next audit or incident.

A role is the unit that decides what a user can see and change inside the instance. Because the Mautic roles documentation describes roles in terms of allowing or denying access to features, the practical design task is to list the functions each group actually needs and then map those functions to roles. Start with a short inventory: who creates campaigns, who manages segments and imports, who works only in reporting, and who should never touch system settings. Confirm the exact feature list in the roles documentation for your Mautic release line before you draft roles, since the set of controls you can assign is defined by the version you run.

Custom roles are most often needed in four situations. Internal marketing staff need to build emails, segments and campaigns without changing system configuration. Sales users may need visibility into contacts and activity without the ability to alter campaigns or delete data. External agencies need access limited to the work they were engaged to do, and they should lose that access when the engagement ends. Read-only reporting users need to view results without editing anything. Each group maps to a different role, and treating them as one group is how over-permissioned accounts accumulate over time.

Account creation is the other half of the design. The default can be changed when you create a user manually, and when you import a user through the API you can select a role at that point. That means your onboarding process, whether manual or scripted, is where least privilege is either enforced or quietly bypassed. Ask your administrators to document which path each group uses, and confirm that scripted imports cannot fall back to the administrator default.

This page walks through designing those roles, assigning them at account creation, and checking that the result matches your intent. It also covers how user authentication interacts with access, including basic authentication and the SAML single sign-on option described in the Mautic authentication documentation, because who can sign in and what they can do are decided by two separate settings. Use the sections that follow as a checklist before you change any production account.

Role configuration options and when each fits

This table compares four ways to assign Mautic access: keeping the default Administrator role, building custom roles per function, choosing a role at manual user creation, and selecting a role during API user import. Read each row for the setup it suits and the maintenance cost it adds, then confirm permission names and scopes on the Roles screen of your release before you build roles.

Option	When it fits	Main trade-off	What to confirm first
Keep the built-in Administrator role	Short pilots, a single operator team, or a bootstrap account used only during installation and initial setup	Every account with this role has full system access, so admin sprawl grows as people join and changes are hard to audit	Which accounts hold Administrator today and whether any can be moved to narrower roles
Custom roles per function	Marketing, sales, and agency teams that need different features, such as campaign editing without access to system settings	More roles to design, document, and review each time a feature or team changes, which needs a named owner	Exact permission names and their scope on the Roles screen of your Mautic release
Role selected at manual user creation	Small teams where an administrator creates each account and can choose the right role at the time	Depends on the person creating the user remembering the correct role, and default Administrator access applies if the role is not changed	Whether your process requires a second person to approve the role before the account is active
Role selected through the API during user import	Bulk onboarding from a directory or HR export, where the same function-to-role mapping must apply to many users	The import script must map job functions to roles correctly, and a mapping error grants wrong access at scale	Which role identifiers the API accepts in your version and how the script handles users who change function
Mixed approach with a small administrator group	Organizations that keep a few full administrators and assign everyone else a function role	Requires a periodic review of who holds administrator access, plus a rule for who may grant it	How many administrators you need and who approves changes to that group

How Mautic assigns a role to each user

Mautic controls what each person can see and change through roles, and each user account is tied to one or more of them. The cards below cover where roles are set up, what happens when a role changes, the default administrator access that new accounts receive, and the planning work that should come before any role is assigned.

Accounts are linked to roles

In the Mautic model, a user account is associated with one or more roles, and each role allows or denies access to features. Access is therefore decided by the role, not by editing each account by hand. When planning, list the features each team needs and map them to roles, then check that every account resolves to the permissions you intended. Verify this with a test account for each role before you rely on it.

Roles are managed under Settings

Roles are created and edited under Settings, Roles in the Mautic administrator interface. Changes to a role are the place to tighten or relax access for a whole group at once. Ask whoever administers the instance to confirm the exact menu path and permission options in the version you run, because the interface can differ between release lines.

Default administrator access for new users

By default, Mautic creates new users with the Administrator role and full system access. You can change this when creating a user manually, or by selecting a role when importing a user through the API. Before onboarding anyone, decide which role new accounts should receive and make sure the process you use sets it explicitly, so no account is created with full access by accident.

Effect of a role change on existing accounts

Confirm in a test environment how a change to a role or an account's assigned role applies to a user who is already signed in or already has an active session. Note whether the change takes effect on the next request or only after sign-out. Record the result so that offboarding or demotion steps can be trusted during an access review.

Check whether multiple roles are supported

Confirm with your version's documentation or by testing in a staging instance whether a single user can hold more than one role. If multiple roles are supported, define how their permissions combine before assigning them. If they are not, design each role to cover a complete job function so that no account needs a workaround.

Design roles from job functions first

Role design is a planning task that should follow a written list of job functions, such as marketing operators, sales users, agency staff and administrators. Map each function to the features it needs, then create the roles. Starting from the software's default roles tends to grant more access than any real job requires, so review the list with the business owners before configuration.

Changing the default that gives new users full administrator access

By default, Mautic creates new users with the Administrator role and full system access. Unless you change that behavior, every account a team member creates through the normal path starts with the widest permissions Mautic offers. For a marketing platform that holds contact records, consent data, campaign logic and integration credentials, that is a risk to plan for before the first user is added, not after.

There are two places where you can change the role. The first is when you create a user manually in the Mautic interface: the user form lets you select the role before the account is saved, so the administrator default is replaced for that account. The second is when a user is imported through the API, where the import request lets you select a role for the new account. In both cases the change applies to that user only. Anyone who creates accounts later, through either path, will receive the default again unless someone sets the role explicitly each time.

Leaving the default in place has consequences beyond the first login. A marketer who only needs to build campaigns and emails can also reach user management, system settings and roles, and an integration or import script that omits a role will create an administrator. Before you rely on a per-user choice, write down which roles your teams need, decide who may create accounts, and make the role selection a required step in your onboarding checklist and in any automation that calls the API.

Accounts created under the default need a review. Open the user list under Settings and check the role on every account, including old accounts, service-style accounts used by scripts and any account created during testing or a migration. Confirm that each administrator still needs that access, remove or disable accounts that no longer belong to a current team member, and record who approved each administrator role so that the review can be repeated at a fixed interval.

Before you plan a change, confirm with the Mautic documentation for your release line and in a test instance whether the default role can be set in configuration rather than per user. The roles documentation describes managing roles under Settings and assigning them to users, but a configuration-level default for new accounts is a separate question. If no such setting exists in your version, the control has to live in your process and in the API calls your team uses, and you should test that every creation path, including imports, produces the role you intend.

How to set up Mautic roles without locking out your administrators

This sequence defines what each job function needs, builds one role at a time and tests each role with a non-administrator account before any user is moved. It ends with reassigned users and fewer administrators, while at least one administrator can still recover the system. Rehearse the full sequence on a staging instance before making changes in production.

List job functions and the data each needs
Before opening Settings, Roles, the team lists every job function that uses Mautic, such as marketing operations, campaign builders, sales users and agency staff. For each function, record the features it uses, the contact data it needs and the actions it must take, including importing contacts, editing campaigns and viewing reports. Identify who may change system settings or manage users, and name the person who approves each of those exceptions. This is done when every function has a written list and each proposed administrator has a documented reason.
Map each function to a role
Turn the function list into a short set of roles, usually one per function or shared access pattern. Write a matrix that shows which screens and actions each role may use, and mark the permissions that touch system settings, user management and integrations, since these carry the most risk. A reviewer should be able to read the matrix in one sitting. This is done when every function is covered and the business owner has signed off that no function has broader access than its work requires.
Create one role at a time
In Settings, Roles on the staging instance, create a single role from the matrix and save it before starting the next one. Use a name that matches the matrix so that reviewers can trace each role back to its job function. Record the exact permissions you enabled so the same configuration can be reproduced in production. This is done when the role exists in staging with the permissions in the matrix and nothing beyond them, and no user has been assigned to it yet.
Test the role with a non-administrator account
Create a test user in staging, assign it only the new role and sign in with that account. Use a separate account because your own administrator login can see screens that the role must hide. Open every screen the role should reach, then try each restricted screen and action directly. This is done when the test login opens only the permitted screens and each action outside the role is refused. If anything is wrong, correct the role, save it and repeat this test before moving on.
Confirm restrictions and the recovery path
With the test account still signed in, try to change a restricted setting, such as a system configuration screen or a user record, and confirm that Mautic refuses the change. Then confirm that at least one administrator account can still sign in and reach every administrative screen. If you use SAML single sign-on, confirm with your identity team that the test account and the administrator account both receive the required email, first name and last name attributes. This is done when both checks pass and the recovery administrator's credentials are stored in your approved secrets process.
Reassign users and change the new-user default
Move existing users to their matched roles in small groups, checking each group after it moves. By default Mautic creates new users with the Administrator role and full system access, so set the role explicitly whenever you create a user manually or import a user through the API. Ask each user to confirm that they see the screens they need. This is done when every active user has a role from the matrix, the new-user process selects a role explicitly, and no group reports missing access that was not already approved in the matrix.
Remove unneeded administrators last
Once every user has a role and the recovery administrator has been confirmed, remove administrator rights from accounts that no longer need them. Do this last so that no step leaves the instance without a working administrator. Keep a short record of who had administrator access before and after the change, and why each remaining administrator needs it. Confirm the same sequence on production only after the staging rehearsal has completed without errors. This is done when the administrator list matches the approved exceptions and the recovery check still passes.

Security and operational considerations for Mautic access

Role design in Mautic limits what each user can see and change, but the controls around those roles depend on how accounts are created, removed and authenticated. The cards below cover the access risks that matter most to security leaders and the decisions that sit with the client or its implementation partner.

Least privilege for agencies and contractors

External agencies and contractors often need campaign or content access without seeing contact records, exports or system settings. Define a dedicated role for each external function and assign it deliberately rather than reusing a marketer role. Review which features each external role can reach, including imports and email sending, before granting access to a production instance. Confirm the permission set against the roles documentation for your Mautic version.

Offboarding when staff leave

Mautic authenticates users with basic authentication, so disabling a person's access is a manual step that the platform will not trigger from an HR system unless you build that process. Document who removes or disables accounts, how quickly, and how API tokens or integration credentials tied to a departing user are rotated. Test the offboarding steps on a staging instance so the process is known before a real departure.

Audit of Administrator role holders

By default, Mautic creates new users with the Administrator role and full system access, so every account added without a deliberate role choice starts with maximum privilege. Run a recurring review of who holds the Administrator role, compare the list with current staff and contractors, and reduce it to the smallest group that needs system settings. Confirm with your Mautic partner how this review is evidenced, since Mautic's documentation does not describe an audit log feature.

Password policy and multi-factor decisions

Basic authentication places password policy, lockout behavior and multi-factor enforcement under your control rather than a central identity service. Decide the minimum password standard, how resets are handled, and whether multi-factor authentication is required for Administrator and API-level access. If your organization needs centralized sign-in, the Mautic authentication docs describe SAML single sign-on, which requires the identity provider to send email, first name and last name attributes. Confirm any additional factor support with the vendor or your partner before committing to it.

Separating production and staging accounts

Staging and production instances often share the same people, which lets test changes, campaign exports or contact data move between environments without oversight. Keep separate user lists, separate role assignments and separate credentials for each instance, and do not copy production user accounts into staging. Decide who may move campaigns between instances and under which approval, so access to one environment does not grant access to the other.

API access and integration credentials

Roles also govern accounts created or imported through the API, where you can select a role when importing a user. Treat API users and integration credentials as accounts with their own owner, role and rotation schedule. Limit each integration user to the functions it needs, record who requested it, and review these accounts alongside human users during each access review.

Single sign-on and role assignment for Mautic users

If you plan to sign Mautic users in through a central identity provider, the first thing to confirm is that Mautic can integrate with a SAML single sign-on identity provider. The Mautic authentication documentation describes SAML, and it requires the identity provider to send three attributes: email, first name and last name. If your identity provider cannot release all three for every user who needs a Mautic account, that gap has to be closed before you design the integration, because Mautic will not have what it needs to create or match the account.

The documentation describes no LDAP option for Mautic authentication. That matters for teams whose directory is Active Directory or another LDAP service, since they cannot assume a direct directory bind. The practical route is to federate that directory through an identity provider that speaks SAML to Mautic, and to test the attribute mapping with real accounts from each group that will use the system. Ask your identity provider team which attribute carries the user's email address and confirm it is the same value Mautic will store.

Single sign-on handles who can sign in. It does not, on the basis of the documentation cited here, decide which Mautic role a user receives. Mautic assigns roles through Settings, Roles, and the authentication docs do not describe group or attribute claims driving role assignment. Before you rely on group membership in your identity provider to place marketers, sales users and agency staff into the right roles, confirm with the Mautic project, or by testing on a non-production instance of your release, whether group or attribute claims can do this.

Until that is confirmed, plan role assignment as a manual step. Create each user, or review each user after first sign-in, and select the role that matches the job. Keep a short register that maps identity provider groups to Mautic roles so that the mapping is written down even though it is applied by hand. Review the register when people change teams, and remove access promptly when someone leaves, since sign-in access and Mautic role access are controlled in separate places.

Also check how new users arrive. The default behavior for new users is the Administrator role with full system access, so an account created through single sign-on or by an integration could carry more access than intended. Confirm which role a new account receives in your release, change the default where your process allows, and test a sign-in by a user from each group to see what they can actually open and change.

Limits to confirm before you rely on Mautic roles

The role model in Mautic is simple to describe but has edges that depend on your Mautic version, identity setup and existing accounts. The cards below list the points to test on a non-production instance before you build a role design on top of them, along with where to confirm each one.

Full permission list for your version

Roles allow or deny access to features, but the exact set of permission toggles can change between Mautic releases. Export or record the permission list from Settings, Roles on a test instance running the same version you plan to deploy. Compare it with the roles documentation for that release line. Any permission your design depends on should be confirmed on that instance, not assumed from an older guide.

Multiple roles per user

Your design may assume that one account can hold a marketing role and a reporting role at the same time. Create a test user, assign two roles, and check which permissions apply in practice. Confirm the answer in the Mautic roles documentation for your version. If a user can hold only one role, consolidate the permission sets before you map people to roles.

Role assignment through SAML

Mautic can use a SAML identity provider for sign-in, but the authentication documentation requires email, first name and last name attributes. It does not establish that group claims set roles. Ask the vendor docs whether role assignment can come from the identity provider. If it cannot, plan a manual or API-based assignment process and decide who owns it.

Bulk changes to existing accounts

Default administrator access applies to accounts created before you change the setting, and those accounts do not change automatically. Before go-live, list every existing user and their current role on the test instance. Then confirm with the Mautic docs and your own test whether roles can be changed in bulk through the interface or the API, or whether each account must be edited one at a time.

Session refresh after role changes

A user who is already signed in may keep the permissions they had at login until the session ends. Test this directly: sign in as a user, change their role on another browser, and check whether access changes without a new login. Record the result for each role change type you plan to make, such as removing access or granting it. Use the answer to decide whether offboarding needs a forced sign-out step.

Questions teams ask before changing Mautic roles

How much effort does a Mautic role design take?

The effort depends mostly on how many distinct job functions need different access, not on the size of the instance itself. The main drivers are:

The number of job functions, such as marketing operations, campaign builders, sales users, reporting viewers and administrators
The number of agencies or outside teams that log in and need limited access
Integrations and campaigns that touch restricted data, such as contact records with consent or sales-owned fields

Each additional function adds permission mapping, test cases and a review step. Ask any partner to break its estimate down by these three drivers so you can see what changes the scope.

Can our team change Mautic roles without a partner?

Yes, a small team with a clear list of roles can usually make the change alone, by working through Settings, Roles in the Mautic interface. The task gets harder when the default administrator model is already built into daily processes, because people who depend on full access will notice removed permissions quickly.

Before you start, confirm three things:

Which existing users currently rely on administrator rights
Whether any campaign, import or API integration runs under an administrator account
Who signs off on each role before it goes live

If those answers are unclear, a partner can help you find the dependencies first.

What does Mautic need from our team to start a role project?

The work needs four inputs from your side, and the quality of these inputs shapes the rest of the project.

A list of job functions that describes what each person does in Mautic today and what they should not do
Named owners for each function who can approve the permissions for their area
Test accounts for each role so the permissions can be checked before users are moved
An access review of current users, including agency and inactive accounts, so you know who holds which role

Keep the review records, since they show how the role model was decided.

How does a partner scope a fixed-scope Mautic roles engagement?

A partner scopes the work by turning your job function list into a written set of roles, permission rules, test cases and deliverables before any changes are made. DeployOpen agrees scope, deliverables and timelines in writing before work starts, and the quote follows from that written scope.

Expect the scope document to cover the number of roles, the systems and integrations included, the testing approach, the handover format and what is out of scope. Ask whether user migration, SSO changes and integration account updates are included, because these are common sources of later disagreement.

Does changing the default administrator role affect integrations?

It can, and you should check this before you change anything. Mautic creates new users with the Administrator role by default, and some teams also use administrator accounts for scheduled jobs, API imports or connected services.

To check, list every account that calls the API or runs background work, then confirm which permissions each one needs. Test those accounts in a non-production instance first, because a missing permission often fails quietly in a campaign or import rather than showing an obvious error.

How should we handle single sign-on when we redesign roles?

Mautic uses basic authentication for users and can integrate with a SAML single sign-on identity provider, which must send email, first name and last name attributes. The documentation describes no LDAP option, so plan your identity source accordingly.

Confirm with your identity team which attribute mapping your provider will send and how role assignment will be kept in sync. If roles are set in Mautic while users sign in through SAML, decide which system is the source of truth so that a user's access does not drift between the two.

How do we know the new roles work as intended?

Test each role with a dedicated test account and check both what the role can do and what it is blocked from doing. Include negative tests, such as confirming that a sales user cannot change consent settings or that an agency user cannot export the full contact database.

Record the results and the named owner who approved them. Repeat the tests after each Mautic upgrade, since a new release can change how permissions are applied, and confirm any changed behavior against the release notes for your version.

How DeployOpen works on this

DeployOpen starts by mapping which marketing, sales and agency users need which Mautic features, then builds and documents roles that match that map. The work is delivered inside your own infrastructure as a fixed-scope engagement, with the default administrator behavior changed before users are created.

How we scope

Inventory every team and external agency that will log in, with the features each one needs to view or change
Agree in writing which Mautic roles will be created, which permissions each grants, and which users map to them
Define how new users are created by hand or by API so the default Administrator role is never assigned by accident

How we build

Create roles under Settings, Roles and test each permission set with a user account for every role
Decide with you whether authentication stays on Mautic basic accounts or connects to a SAML identity provider that sends email, first name and last name
Test that restricted roles cannot reach campaigns, contacts or settings outside their remit before the configuration is accepted

How we hand over

Deliver a role matrix that lists each role, its allowed and denied features, and the teams assigned to it
Document the user creation procedure, including the role selection step for manual creation and API imports
Walk your administrators through adding users, changing roles and reviewing access on a regular schedule

How we support

Review role assignments when Mautic is upgraded, since a new release line may change feature names or permissions
Offer ongoing support and access reviews as a retainer after the fixed-scope engagement ends
Confirm with your team which access review cadence and approval steps your own policies require before go-live