Accounts and workspace access
Your account lets you sign in to a dtxWiki server. Your workspace membership determines which shared space you can enter and what you can do there. A server administrator operates the whole installation and can start account recovery. These are separate responsibilities.
Choose a role
| Workspace role | Typical use | Main abilities |
|---|---|---|
| Viewer | A colleague who needs to consult knowledge | Read accessible content and use read surfaces; editing actions are restricted |
| Editor | A person who contributes knowledge | Create and edit Context content, work with Agent drafts and Chats, subject to review and policy |
| Owner | A person responsible for this workspace | Editor abilities plus membership, roles, sharing, and workspace policy management |
Role permissions still interact with page state, content sensitivity, and review policy. For example, an author-private MCP edit is visible only to its author, while browser Save draft/autosave creates an unpublished draft readable by workspace Editors and Owners. Viewers still need a published version. An Editor role does not make every protected action available. Review markers in the page explorer appear only for Editors and Owners. Every role can mark items with Add to my favorites; favorites are shown only to the person who set them.
In Settings → Attachments, each member sees uploads on pages they can read. Viewers and Editors see their own uploads, and Owners also see other members' uploads. Editors can delete their own unused uploads. Owners can delete any unused file in the list and set how long unused uploads are kept with Unused file auto reclamation. Viewers can look but not delete. See Privacy and safe sharing for automatic cleanup.
Settings → Labs is a personal display choice, not a role. Show Knowledge Map menu, Show Ask menu and Show Agent menu change only which experimental menus that person sees in that browser; they neither grant nor remove abilities.
Membership applies to the whole workspace, not one folder or page. If you need to share only a subset of your work, create a collaborative workspace for that material. Adding someone to your Personal Workspace changes who can access that space.
Add an existing account to a workspace
As an Owner, select the intended workspace and open Settings → Members & access. Existing members are listed first. Open the separate add-member dialog, enter the active account's exact user UUID or registered account email, choose a role and inspect the confirmation before adding. Ask the person to open Account → User ID → Copy user ID. This UUID identifies an email-less account too; the Automatic username is generated separately and is not a login name. Partial names help find members but do not identify an account to add. An unverified IdP profile email is not an account-email lookup key.
A company directory is offered only when the operator enables a validated provider/tenant and the requesting Owner belongs to that scope. Check the UUID and trusted organization marker, not only a matching display name. The add action does not create an account or send an invitation; use the server's signup, configured SSO or operator account-creation procedure first.
Membership covers the entire workspace. Giving Owner authority grants control of members, policy and sharing. The private workspace created at signup is ordinary: another Owner can take over and deletion does not recreate it. User-created slugs cannot use the reserved personal- prefix.
Joining a discoverable workspace
Workspace visibility and membership are separate:
- Private: only members can discover and enter it.
- Team: signed-in users on the server can discover it, but membership is still needed to enter.
- Public: visitors can discover its public profile; internal knowledge still needs membership.
If join requests are enabled, a signed-in non-member can request access. Owners review requests in Members & access; approval adds the person as a Viewer. An owner can change the role later if the person needs to contribute.
Visibility alone does not put every page on the public web. A published Context version must be separately published to the web. See Sharing.
Create a server account
This step is for a server operator. Team and remote modes close self-sign-up by default. For a systemd installation:
sudo dtxwiki users add person@example.com
For Docker, from the existing infra/prod directory:
docker compose exec app dtxwiki users add person@example.com
The command asks twice, with hidden input, for a password of 8–128 characters, then creates the account and its Personal Workspace. A password outside that range stops it with user add failed: password must be between 8 and 128 characters, and an invalid email is rejected; in both cases no account is created. To set a display name of up to 32 characters, add --display-name "Example Person". Without it, dtxWiki uses the part of the email before @, or User when that part cannot be used. Email/password sign-in uses the account email, not the generated Automatic username shown in Account. Arrange a secure initial handover; the user should then choose a new password with Account → Update password. Creating the account does not add it to an existing shared workspace.
For a local installation with signup enabled, the user can instead choose Sign up in the browser. Follow installation and first login for the separate server-admin grant. The first registered account is a workspace Owner, not an automatic server administrator.
An operator can also add an existing account by the workspace’s actual slug, its URL-friendly identifier:
sudo dtxwiki workspace members add person@example.com \
--workspace YOUR_WORKSPACE_SLUG --role viewer
sudo dtxwiki workspace members list --workspace YOUR_WORKSPACE_SLUG
Do not assume the slug is default; Personal Workspaces use user-specific slugs.
On a local installation, run these dtxwiki users … and dtxwiki workspace … commands without sudo, and stop dtxWiki first: press Ctrl+C in the terminal running it, run the command, then start dtxwiki again. While the app is running, such a command stops with a long error ending in stop dtxWiki (server and worker) first: … and changes nothing. An administrator who needs to keep the app running can instead set DTXWIKI_AUTO_BOOTSTRAP=false for the command, for example DTXWIKI_AUTO_BOOTSTRAP=false dtxwiki workspace members list --workspace YOUR_WORKSPACE_SLUG.
Change a display name or login email
People cannot replace their display name or an existing account email in the app. An email-less account can use Account → Login methods → Add account email when SMTP and password login are enabled, confirming the address in the same browser. Other changes require the operator and the user UUID. dtxwiki users add prints the ID when it creates an account, and the --json output of dtxwiki workspace members list shows each member's user_id.
These changes refuse to run while dtxWiki's server or worker is running, on every kind of installation. On a systemd server:
sudo systemctl stop dtxwiki dtxwiki-worker
sudo dtxwiki workspace members list --workspace YOUR_WORKSPACE_SLUG --json
sudo dtxwiki users set-display-name USER_ID --display-name "Example Person"
sudo dtxwiki users set-email USER_ID --email new.person@example.com
sudo systemctl start dtxwiki dtxwiki-worker
Run only the change you need. Each one prints Input repaired; database revision preserved. when it succeeds. On a local installation, stop the app with Ctrl+C, run the same commands without sudo, then start dtxwiki again. With Docker, run docker compose stop app worker in infra/prod, run each command as docker compose run --rm --no-deps app dtxwiki …, then start the services with docker compose up -d app worker.
A display name needs 1–32 characters, without spaces at the start or end. Changing the email signs the person out of every browser, cancels unused password-reset links and marks the address as unverified. Email recovery works for that account again after the person verifies the new address. If an upgrade from v0.1.2 is refused because of names or emails, follow Backups and maintenance.
Password changes and recovery
To change your password while you can still sign in, open Account (the person icon in the top bar) and choose Update password. A new password needs 8–128 characters, and spaces count as part of it. Existing passwords up to 128 characters keep working, so you do not have to change them. If you cannot sign in, use Forgot your password? when server mail recovery is available. Email recovery depends on a configured mail service and an eligible verified address. Otherwise contact the server operator, not just a workspace owner.
v0.1.2 accepted passwords longer than 128 characters. Such a password no longer signs in, and Update password cannot replace it because that page asks for the current password. Reset it with Forgot your password? or an operator link, described below.
When the server has a configured canonical HTTPS URL, the operator can issue a one-time link without choosing or viewing your new password:
sudo dtxwiki users issue-password-reset person@example.com --delivery link
The administrator-issued link expires in 30 minutes by default and requires an interactive terminal to display. The person who opens it chooses a new password of 8–128 characters. Completing any password reset ends the user's browser sessions. For administrator/CLI recovery, PAT/MCP/OAuth credentials are revoked when the issuer or recipient requests it; if compromise is suspected, the operator should use --revoke-api-tokens. In contrast, recovery started through public Forgot your password? always revokes those credentials on completion. Reconnect AI apps after that recovery.
SMTP is optional for the administrator's explicit --delivery link route, but the HTTPS representative URL is still required. A default local HTTP installation does not have that recovery-link mode configured. Email self-service recovery additionally requires SMTP setup and a verified account email; configuring mail does not retroactively verify every account.
The User accounts tools below are for server administrators. Server administration does not automatically grant membership in every workspace.
Server administrators also get an Attachment scope choice in Settings → Attachments. All workspaces lists attachment details from every workspace on the server, including workspaces they are not members of: the workspace, file name, page title, uploader and upload time, without previews. They can delete unused files there, and dtxWiki records each deletion. This view does not make them members, let them open the pages, or let them change a workspace's cleanup setting.
AI access has one more boundary
An AI app needs both your workspace membership and a credential that allows that workspace and action. Adding a workspace to an access key does not bypass your role. Removing workspace access from the key stops that connection reaching it. When you create a key, View and select workspaces opens the Allowed workspaces dialog, which lists only workspaces you are a member of. One access key or OAuth app approval can cover at most 256 workspaces. After a member is removed, or a workspace is removed from a key or app, the affected connection shows Credential revoked under Settings → MCP access → Connected MCP clients. See Connect an AI app.
External identity, deletion and recovery
Email-less accounts can receive membership and server administration by UUID. See SSO operation and account management for linking/unlinking. Deletion immediately revokes access, then retains the account for the configured period; an administrator can restore it before cleanup. Check sole-admin workspace handover and retained shared history first.
Use a UUID for membership and administrator handover
An email-less account can be added or removed by exact user UUID. Use the existing installation's maintenance environment, with services stopped as described above; omit sudo for your local installation:
sudo dtxwiki workspace members add --user-id USER_UUID \
--workspace YOUR_WORKSPACE_SLUG --role viewer
sudo dtxwiki workspace members remove --user-id USER_UUID \
--workspace YOUR_WORKSPACE_SLUG
The remove command revokes membership of that whole workspace. Choose only the action you intend. Handing over the last server-administrator role needs a separate operator grant to another active account:
sudo dtxwiki admin grant --user-id OTHER_ACTIVE_USER_UUID
sudo dtxwiki admin list
Verify the new administrator can sign in before the departing administrator withdraws. Giving a workspace Owner role does not perform this server-level handover.
Server account tools
A server administrator opens Settings → User accounts, completes recent identity confirmation when requested, and searches by name, account email, user ID or workspace. Open the intended account's menu rather than acting on a matching display name alone.
| Control | Use and limit |
|---|---|
| Account deletion retention | Choose 0–36500 whole days, 30 by default. It changes new deletion requests; existing deadlines stay fixed. At zero, cleanup can start on the next worker sweep. |
| Delete account, Restore account | Inspect the impact before revoking access, or restore a pending deletion before cleanup starts. Sessions and API/OAuth credentials stay revoked after restoration. |
| Appoint an admin → Make admin | Select an active member to preserve a workspace held for deletion with the account. This grants workspace administration, not server-administrator authority. |
| SSO sign-ups waiting on an email conflict → Show pending requests | Inspect the requester and current account; choose Release the address or Keep the existing account and record the reason. Release deactivates the holder and revokes credentials while retaining data. |
| Reconnect SSO identity | After independently verifying ownership, reconnect the selected UUID's identity. Data and roles remain; sessions and credentials are revoked. |
| Server audit log → Show records | Read server-level account, credential and administrator changes, including CLI activity. This requires recent confirmation and records that the log was accessed. It is separate from workspace Activity. |
For password recovery, read the delivery and token-revocation options before issuing a link. Use the existing user's UUID for an email-less SSO recovery; a reset-email form cannot restore its unavailable IdP identity. Account management and SSO operations explain those flows.
Implementation evidence: account and membership commands, account input rules, display name and email changes, effects of an email change, refusal while running, member/access screen labels, recovery UI, recovery and credential revocation, attachment views, server-wide attachment list.