Appearance
Account and access
What this page covers: how you sign in to the mmune console, what each role is allowed to do, what is available for multi-factor authentication and single sign-on, how long a session lasts, what the license states mean and how an administrator applies a renewal, and what a real installation requires.
Prerequisites / permissions: you need the address of your mmune installation and an account on it. Reading this page needs nothing else. The sections on applying a license need the administrator role. Day-to-day operations tasks such as restarting the backend or rotating secrets are handled by your administrator and are not covered here.
Related pages: Concepts for vocabulary, Compliance for the License card, and for the HTTP details API overview and Security and platform API.
Signing in
Every page of the console sits behind a sign-in form on a real installation. The form is titled "Sign in to mmune" and asks for an email and a password. After a successful sign-in you land on the page you asked for, so a bookmarked /alerts link opens Alerts once you are in.
If the form shows "Sign-in failed. Check your email and password.", one of four things happened. The password is wrong, the account does not exist, the backend could not be reached, or you were rate limited. The form uses the same message for all of them. mmune allows 5 failed attempts per email and client address in a 60 second window. The sixth attempt is refused until the window passes, so wait a minute before trying again. A successful sign-in resets the count.
Signing in and failing to sign in are both written to the audit trail, with the email and the client address.
A demo environment has no sign-in form. It shows sample data, so there is no account and nothing to protect. See Concepts.
Accounts
The first administrator account is created by the person who installs mmune. Further access is managed by your administrator. The console has no screen for creating users. Ask your administrator for the credentials that apply to your installation, and do not reuse a password from another system.
Access comes in two levels. An account either has read-only access (role user) or full administrator access (role admin).
There is no self-service API key creation. A script or tool that needs to call mmune signs in with an account and uses the token it gets back. The same goes for the read-only MCP server, which takes a token from the sign-in call. See Using mmune from an AI agent.
Changing a password
The console has no screen for this. An account can change its own password through the API, POST /api/v1/auth/change-password with the current and new password. If you have forgotten a password, ask your administrator to reset it.
Roles and permissions
A token carries two things: a role (admin or user) and a list of permissions. The role admin is allowed everything. Otherwise each permission opens one level of use.
| Level | Who has it | What it lets you do |
|---|---|---|
read | Every account | See every page, tab and list. Ask questions in Workspace Chat. Draft a plan, which does not run it. Use the read-only suggestion calls such as mapping suggestions and semantic matching. Change your own password and your own MFA enrollment. |
write | Administrator accounts | Anything that changes state: start discovery scans, configure, test and register integrations, re-introspect, resolve duplicate groups, dismiss findings, mute a drift field, acknowledge and resolve incidents, create tickets, save alert settings, generate the Passive Audit Report, run a plan, start most agents, ingest documents. |
admin role | Administrator accounts | Everything above, plus a short list of estate-wide controls: change the healing mode, change containment settings, start a Deep System Scan, apply a license, copy the renewal attestation, clear the logs, register or remove deployed discovery agents, and read the audit events. |
This is the rule mmune applies. Every request needs a valid token with read. Any request that changes something (anything other than a read) additionally needs write or the admin role, except for a short list that a read-only user may call: changing their own profile, password, session and MFA, asking chat questions, running retrieval queries, getting mapping or semantic suggestions, and drafting a plan. A second short list needs the admin role no matter what. The exact lists are in the API overview. Chat is open to read-only users. By default chat has no action tools at all, and where an installer has turned them on, each one checks your write permission before it runs.
Chat questions can cost AI budget when a real AI provider is configured, so a read-only user can spend it. The Spend tab in Workspace shows usage and caps.
What a refusal looks like
The server decides, not the page. Most pages show you every button, including ones your role cannot use, and the refusal arrives when you click. The message is "Your role cannot do this. Ask an administrator." with HTTP status 403. The page shows it as an error, and how it appears varies by page. Some individual routes return a plainer message such as "Permission 'write' required". Both mean the same thing. A refused change leaves a record in the audit trail with who tried and what they tried.
If you need access you do not have, ask your administrator to change your access or to do the task for you.
When a role change takes effect
Permissions are read from your token, not looked up on every request. If your account's permissions change, sign in again to get a token that reflects it.
Sessions
When you sign in, mmune issues a token that lasts 30 minutes by default. Your administrator can change the length.
The console keeps the token in the browser's session storage for that tab. This has some practical effects. A new tab or window needs its own sign-in. Closing the tab ends the session on your side. A normal page reload keeps you signed in. The console does not renew the token behind the scenes, so after 30 minutes the next request is refused and the sign-in form appears again, at the same address. The same thing happens if an administrator rotates the signing secret, which signs everyone out.
Close the tab to end your session.
Multi-factor authentication and single sign-on
mmune supports time-based one-time passwords, with backup codes. MFA enrollment and sign-in with a code are available through the API. POST /api/v1/auth/mfa/setup returns a secret and a QR code, POST /api/v1/auth/mfa/enable confirms a code from an authenticator app and returns the backup codes once, and POST /api/v1/auth/mfa/disable turns it off after a password check. A login for an enrolled account then returns a short challenge that must be completed with POST /api/v1/auth/mfa/verify-login. If you enroll an account, store the backup codes, because they are shown once and the account has no other recovery path.
There is no single sign-on. The /oauth/callback address in the console serves integrations that authenticate to external systems, not user sign-in.
License states
mmune checks its license offline, against public keys built into the install, so it works with no connection to the vendor. The license sets how long you may use mmune and how many systems you may register. The state is checked at startup and again every hour by default. You see it on the License card of the Compliance page, and in a banner above every page when the state needs attention.
| State | What it means | What still works |
|---|---|---|
valid | A license verifies and has not reached its expiry date. | Everything. |
grace | The expiry date has passed but the grace window has not ended. | Monitoring and registering new systems, within the cap. Renew soon. |
expired | The grace window has ended. | Sign-in, reading every page, and applying a license. Monitoring stops and new registrations are refused. |
missing | No license was found. | Sign-in, reading pages and applying a license. Monitoring does not start and registrations are refused. |
invalid | A license was found but did not verify, or it is bound to a different install. The card shows the reason. | Same as missing. |
A license also sets a cap on registered systems. At the cap, registering a new integration is refused with the code license_cap_exceeded until you remove one or raise the cap. Integrations that were already registered are never switched off by the cap, so a restart at the cap still comes up normally. If the system clock appears to have been moved backwards, the card says so, and expiry is judged against the latest time mmune has seen, so winding the clock back does not extend a license.
Licensing never affects who may call what. Authorization does not read license state, so an expired license cannot lock the administrator out of renewing it.
Apply a renewal
Applying a license needs the administrator role.
- Sign in as the administrator and open Compliance.
- On the License card, click Apply license.
- Paste the token your vendor sent. It is one long text string, written here as
<LICENSE_TOKEN>. - Click Apply.
On success the card updates at once and monitoring restarts by itself if it had stopped. No restart of mmune is needed. If the token is rejected, the reason is shown and the license already in force is left alone. The reasons include a malformed token, an unknown signing key, a failed signature, and a license bound to a different install. The full list is in the Security and platform API. The same action through the API is POST /api/v1/license with {"token": "<LICENSE_TOKEN>"}.
For a renewal your vendor may also ask for the attestation, a signed usage report. The Copy renewal attestation button on the same card produces it, and it needs the administrator role as well. Both steps are described in Compliance.
Where a license can come from matters when you renew. mmune looks first at a license applied through the console or API, then at a license file on the host (by default /var/lib/mmune/license/mmune.license, or the path in MMUNE_LICENSE_FILE), and last at the MMUNE_LICENSE environment variable. It uses the first one that verifies. Because an expired license still verifies, once a renewal has been applied through the console, putting a newer file on the host will not replace it. Apply later renewals through the console as well.
One thing to plan for when upgrading an installation that has no license yet: it starts in the missing state and monitoring does not run until a license is delivered. Deliver the license with or before the upgrade.
Demo and real installations
A demo environment shows sample data and needs no license. A real installation shows your estate, and what you see depends on how it was installed. The person who installs mmune sets the variable MMUNE_MODE to prod for a real installation. You cannot change it from the console.
In a production installation a license is required, otherwise the state is missing. Interactive API documentation is switched off. Monitoring uses your real integrations only and never shows simulated data. The Validation Agent on the Workspace Agents tab is not available. Confirm with your administrator that your installation runs in production mode. The Compliance page includes an authentication control whose evidence text says whether mmune is running in production mode.
Related pages
Concepts defines the terms used here. Compliance holds the License card and the renewal steps. Workspace has a table of which action needs which permission.