Dashboard and roles

The dashboard is at /dashboard under your site URL. The server renders every page, and every action is an HTML form. It works with JavaScript off.

First sign-in

1. Open https://pay.example.com/dashboard/setup.
2. Enter an email address and a password of 12 characters or more. Enter the password again.
3. Click Create account. This account becomes the root user. There is only one root user. If the install has no project, Turmite also makes a project called "My shop".
4. Open Account and turn on two-factor authentication.

After sign-in, Turmite opens your first project. An admin with no project goes to New project. A member with no project goes to Account.

The setup page works only while the database has no users. After that, sign in at /dashboard/login.

Pages

The Project menu at the top of the sidebar switches between projects. Admins see New project there. Each project has these pages, in this order:

Page	Use
Overview	Setup steps, totals of the last 30 days and recent payments. A warning lists payments whose sweep is late or failed
Payments	List and detail of payments. The detail page shows each sweep with its status, and has Mark as paid and Mark as refunded
Invoices	Invoices, and New payment link to make one by hand
Wallets	Settlement setup per network, and Deploy now for the EVM factory. See Wallets per chain
Payouts	Tabs Payouts, New payout, Address book and Limits. See Payouts
API keys	Create and revoke keys for the merchant API
Webhooks	Endpoints with Send test and Delete, and deliveries with Retry. See Webhooks
Settings	Tabs General (name, payment and invoice windows, IPN signature header, IPN secret), Checkout (logo, accent colour, theme, message, support contacts, return URL and hosts), Exchange (Trocador) and Domain (checkout domain)
Team	Project members and their roles

Global admins also see a Server section in the sidebar:

Page	Use
Server → Networks	Per network: on or off, confirmations, nodes with status, height and the node in use, last block, assets and tokens
Server → Hot wallets	Make or import hot wallets, see their balances, assign them to projects
Server → Users	Add users, set the global role, disable users and reset two-factor
Server → Audit log	Every sign-in and sensitive action, 100 entries per page
Server → Updates	The installed version, the latest release, security advisories, Check now and the daily check setting

Roles

Each user has one global role. Members also have one role in each project they belong to.

Global roles

Role	Access
root	Everything. The first user. Only root adds admins, changes global roles, disables admins and resets two-factor for other users
admin	Every project with the project_admin role, plus new projects, checkout domains, networks, nodes, hot wallets, users, the audit log and updates
member	Only the projects the user belongs to, with that project's role

Project roles

Role	Access
project_admin	Everything in the project except the checkout domain: settings, IPN secret rotation, wallets, creating API keys, team, Mark as paid and Mark as refunded, payouts, approvals, the address book and payout limits
developer	Create payment links, add and delete webhook endpoints, send tests, retry deliveries, revoke API keys, show the IPN secret. Read everything else
read_only	Read access to the project

Give each person the lowest role that works. Use developer for integration work and read_only for support staff. Give project_admin only to people who can approve payouts.

Two-factor authentication

Turmite uses TOTP codes from an authenticator app.

1. Open Account. The link is your email address at the foot of the sidebar.
2. Under Two-factor authentication, click Set up two-factor.
3. Scan the QR code with an authenticator app, or enter the key that the page shows.
4. Enter the code that the app shows, and click Turn on.

To turn two-factor off, enter a current code and click Turn off. On mainnet, Turmite refuses sensitive actions while two-factor is off. On testnet, those actions work without a code until you turn two-factor on.

After you turn on two-factor authentication, Turmite asks for a code at each sign-in.

Actions that need a fresh code

A sensitive action needs a new code, also during an active session:

• creating API keys;
• showing or rotating the IPN secret;
• saving a wallet, and Deploy now;
• saving the exchange settings, and removing the Trocador key;
• setting the checkout domain;
• creating, approving, rejecting, cancelling and resolving payouts;
• adding and removing address book entries;
• saving payout limits;
• Mark as paid and Mark as refunded on a payment;
• making, importing and assigning hot wallets;
• adding or removing an RPC node, lowering the confirmations of a network, turning assets on or off, adding a token;
• adding a user, making a user an admin, and resetting two-factor for a user;
• adding a project admin to a team;
• turning off update checks;
• turning two-factor off for your own account.

These actions need no code: revoking an API key, raising confirmations, turning a network on or off, stopping or starting payments on a network, the General and Checkout settings, other team changes, making an admin a member, disabling users, webhook endpoints and payment links. A new password needs the current password.

Each code works one time. After 5 wrong codes, Turmite locks two-factor checks for that user for up to 15 minutes. The lock is in memory. It ends early when the api process restarts.

Lost authenticator

The root user can reset two-factor for another user under Server → Users, with a fresh code. Without the root account, a person with shell access to the server can clear two-factor for a user:

cd /opt/turmite
sudo docker compose exec api turmite user reset2fa [email protected]

The command also signs the user out of every session. The user then signs in with the password and enrols again. The audit log records the reset as user.2fa_reset.

Sign-in protection

• Passwords have at least 12 characters.
• Turmite hashes passwords with Argon2id (64 MiB, 3 passes). At most four hashes run at one time.
• Sign-in is limited to 10 attempts per minute per IP address and per email address.
• Sign-in with two-factor has two steps: the password at /dashboard/login, then the code at /dashboard/login/code. The second step must follow within 5 minutes.
• A disabled user cannot sign in, and the user's sessions end.
• A password change ends the other sessions of the user. The session that changed the password stays.
• Turmite takes the client IP from X-Forwarded-For only when the request comes from TURMITE_TRUSTED_PROXIES. See Reverse proxy, Cloudflare and firewall.

Sessions

Property	Value
Cookie name	turmite_session
Flags	HttpOnly, SameSite=Strict, Secure on https://
Path	The path of the site URL, for example / or /pay
Lifetime	12 hours without activity. Each request extends it, up to 7 days after sign-in

Each dashboard POST request must carry an Origin header, or a Referer header, with the origin of the site URL. Turmite refuses other requests with 403 Cross-site request refused. A proxy that changes Origin breaks the dashboard. See Private dashboard for a private entrance that keeps this check.

Audit log

Turmite writes an audit entry for each sign-in and each sensitive action, for example two-factor changes, API keys, the IPN secret, project settings, wallets, hot wallets, payouts, networks, nodes, manual payment changes and user changes. The worker adds node.failover when it moves a network to another node. Each entry has the time, the user or system, the project, the action, the target and the IP address. Global admins read it in Server → Audit log. Project admins do not see the audit log.

Update checks

A minute after start and then once a day, the worker reads the latest release and the security advisories of loruorg/turmite on GitHub. The request sends the version in its User-Agent and nothing else. When a newer release exists, admins see a banner with Dismiss. When an advisory affects the installed version, admins see a red banner that stays until the server runs a fixed version. When SMTP is set, admins also get one email for each critical or high advisory.

The check is on by default. To turn it off, open Server → Updates, clear Check for updates every day, enter a two-factor code and click Save. If you turn it off, watch the releases and advisories yourself.

To install an update, see Upgrades.