users.md

Server users, login, and permissions

Usage

If the deployment is unclaimed, complete the one-time setup first. Administrators use the current Operator token:

1. Select the administrator token login option on the login page.
2. After login, open Settings → User management.
3. Click Create user.
4. Enter an email address and select the user or administrator role.
5. Submit the form. Save the password generated by Server and give it to the user.

Passwords appear only once in the create or reset response. Users enter their email and password in the default email login form. Self-registration, email delivery, and password recovery are not supported. An administrator must reset a forgotten password.

Email addresses are trimmed, converted to lowercase, and unique within the deployment. Account IDs remain stable after creation. Flow ownership uses the account ID, not the email address. Generated passwords have 144 bits of random entropy. The database stores a separate random salt and a scrypt hash, not the plaintext password.

Permissions and resource ownership

Capability	User	Administrator
Create, edit, publish, and run owned Flows	Allowed	Allowed
Read another account's Flow, Revision, Publication, Run, or results	Not allowed	Not allowed
Select configured Connector accounts and LLM capabilities in owned Flows	Allowed, subject to upstream authorization	Allowed, subject to upstream authorization
Create users, reset passwords, enable or disable accounts	Not allowed	Allowed
Change Connector, LLM, or Integration configuration; create external connections	Not allowed	Allowed
Read or manage own Variables	Allowed	Allowed
Read or manage another account’s Variables	Not allowed	Not allowed
Manage Event Sources	Not allowed	Allowed

Deployment roles are independent of OOMOL Team membership roles. Local administrator status does not increase upstream Connector permissions. Cross-account resource requests return 404 for the resource without revealing whether it exists. Insufficient management permission returns 403 authorization.denied. Error-handler Flows can subscribe only to upstream Flows owned by the same account. Lists, totals, pagination, idempotency keys, and realtime subscriptions follow the account boundary.

Login and sessions

These interfaces belong to the Server host, not to the public cross-deployment Control API contract. JSON requests and responses use version: 1.

Method	Path	Request	Success response
GET	/auth/session	None	Current login state and user
POST	/auth/session	{ version: 1, token }	Establish an Operator session
POST	/auth/user-session	{ version: 1, email, password }	Establish an email account session
DELETE	/auth/session	None	204; clear the authentication Cookie

For a logged-in account, user is { userId, email, role }, where role is admin or user. Operator returns { userId: "operator", email: null, role: "admin" }. Without login, user is null. Sessions use an HttpOnly, SameSite=Strict Cookie with a 30-day lifetime. HTTPS deployments use OPEN_FLOW_SESSION_COOKIE_SECURE=true. Email and Operator login share the existing authentication rate limit. Password verification limits concurrency to control scrypt memory use. Unknown email addresses, incorrect passwords, and disabled accounts return the same authentication error.

Resetting a password or changing an account's enabled state increments its credential version and invalidates old Cookies. Enabling the account again does not restore old logins. Realtime subscriptions check the session before sending each subsequent event and close the stream if the session is invalid. Browser logout clears the browser Cookie. Clients should discard the old Cookie.

User management interfaces

All interfaces require administrator authentication and return Cache-Control: no-store.

Method	Path	Request	Success response
GET	/auth/users	None	{ version: 1, users: User[] }
POST	/auth/users	{ version: 1, email, role }	201 { version: 1, user, password }
PUT	/auth/users/:userId	{ version: 1, enabled, expectedRevision }	{ version: 1, user }
POST	/auth/users/:userId/password	{ version: 1, expectedRevision }	{ version: 1, user, password }

User contains userId, email, role, enabled, revision, and millisecond timestamps createdAt. It does not contain a password hash or salt. Email conflicts and concurrent account changes return 409 user.conflict. An unknown account returns 404 user.not-found. Administrators cannot disable the account they are currently using. Disabling an account preserves its Flows and historical execution data. It does not stop existing background Runs or published Triggers.

Existing data upgrades

SQLite migration 0042 assigns existing global Variables to operator, preserving names, values and timestamps. Variables are not copied to email accounts. Each account has an independent 200-variable limit; background execution resolves the Flow owner’s variables. Existing execution snapshots remain unchanged. SQLite migration 0041 extends personal Token storage with Operator credential binding, preserving existing email account Tokens. SQLite migration 0037 creates account storage in the startup transaction and assigns old Flows to operator. Existing Flow creation and Draft/Live Run idempotency keys move into Operator scope. Existing clients can retry the same requests. Revision content, Publications, Runs, results, and external Trigger identities remain unchanged. Local account ownership does not modify fixed execution capability snapshots. Accounts and session signing secrets persist in the Server data volume. Restarting does not regenerate account passwords or change Flow ownership.

Personal access Tokens and MCP

After Operator or email login, open Agent access, enter a client name, and create a personal access Token. CLI and MCP clients use these Tokens. The plaintext Token appears only once after creation. The page provides copy and revoke actions. The Token list and database do not store recoverable plaintext. The database stores a SHA-256 digest.

Clients use /v1/mcp with Authorization: Bearer <personal-token> and do not need a browser Cookie. The Token can also call Server APIs that the account can access. It has the account's permissions and can access only that account's Flows. Administrator status does not expand Flow visibility. Tokens have no fixed expiry and can be revoked individually. Email account Tokens are also invalidated by password reset or account disablement; re-enabling an account does not restore them. Operator personal Tokens are bound to the active Operator credential fingerprint: the environment token digest or the stored credential revision. They authenticate only while that fingerprint matches. Switching credential sources also invalidates them for the new source. Browser logout does not revoke Tokens. The deployment Operator credential remains available for Operator login and existing machine clients. Personal Tokens cannot be used as Operator login credentials.

The following management interfaces accept only an Operator or email account's login Cookie. They do not accept Bearer Tokens or allow callers to select another account:

Method	Path	Request body	Response
GET	/auth/tokens	None	{ version: 1, tokens: [{ tokenId, name, createdAt }] }
POST	/auth/tokens	{ version: 1, name }	201 { version: 1, credential: { tokenId, name, createdAt }, token }
DELETE	/auth/tokens/:tokenId	None	204; idempotently revoke the current account's Token

After trimming, names must contain 1–100 characters. Responses use Cache-Control: no-store. Cross-origin requests are rejected.