Sign-in and permissions
≈ 15 min · you will have an app with sign-in, roles (for example staff, manager, admin) and APIs open only to the right roles.
You write no sign-in code; you declare the roles and how people sign up in app/auth.ts. At build time manh.run generates the users table, the sign-in API and the user admin API. The token is a JWT sent in the Authorization header, signed with the app’s own JWT_SECRET.
Declare app/auth.ts
export default {
roles: ["admin", "manager", "staff"],
defaultRole: "staff",
signup: "closed",
providers: ["google"],
labels: { manager: "Store manager" },
};- The first role manages users. It goes to the first account registered in the app owner’s workspace preview while nobody holds that role yet. On the live app every sign-up gets
defaultRole, so a stranger cannot claim admin by registering first. signup: "open": anyone can register."closed": only that first admin signs up; staff are added on the/userspage with Add account (name, email, first password, role).providers: ["google"]adds the Sign in with Google button. Theauthblock writes this line already. manh.run uses its own Google app, so you register nothing and the app holds no key. A Google account and a password account with the same email are the same person.labelsnames the roles on screens. Common roles (admin, owner, manager, staff, technician, cashier…) already have Vietnamese names.profile: { branchId: "int" }adds a column to the users table; the value is onuser.branchIdin every handler.- The file holds literal values only and ends in
.ts, because manh.run reads it and never runs it.app/auth.tsxis ignored andcheckreportsconfig.wrong-extension.
manh.run generates api.auth.login, api.auth.register, api.auth.me, api.users.list, api.users.create, api.users.update and api.users.members() (active users for people pickers, callable by anyone signed in). To change one part, write your own file at the generated file’s path; manh.run uses the file in the project.
POST /auth/login blocks after 5 wrong passwords for one email, or 30 from one IP address, within 15 minutes: it answers 429 with code TOO_MANY_ATTEMPTS and a Retry-After header. A correct sign-in resets the counter. The sign-in screen only needs to show the error’s message.
Who may call an API
Each handler exports access. Without it, only signed-in users may call the handler.
import { z } from "@hono/zod-openapi";
import { moveOrder } from "../../repository";
export const access = ["manager", "admin"];
export const schema = { body: z.object({ to: z.enum(["confirmed", "done"]) }) };
export default (c, { user, param, body }) => moveOrder(user, param.id, body.to);"public": anyone."user": anyone signed in.["manager", "admin"]: only these roles.- Not signed in gets
401with codeUNAUTHENTICATED; the wrong role gets403with codeFORBIDDEN. Access is checked before the request body, so a caller with the wrong role never sees a400that reveals the data shape. - An unknown role makes
checkreportaccess.unknown-role. A write API left"public"gets the warningaccess.public-write; that is fine for a contact form or a public booking. - A
"public"write is limited to 30 requests per 10 minutes per IP and route; past that it answers429with codeRATE_LIMITED. Change it withexport const rateLimit = { max: 5, windowSec: 600 }, turn it off withexport const rateLimit = false(webhooks from another system). - Filtering data by user (orders the user created) still lives in the repository:
where(eq(orders.createdBy, user.id)).
For a whole folder, put export const access = ["admin"]; in that folder’s middleware.ts, for example app/(admin)/middleware.ts. A handler that declares its own access uses that value.
The session in the UI
import { LoginForm, ProFormText } from "@ant-design/pro-components";
import { useNavigate } from "react-router-dom";
import { useApiClient } from "app/api";
import { signIn } from "app/hooks";
export default function LoginPage() {
const api = useApiClient();
const nav = useNavigate();
return (
<LoginForm title="Đăng nhập" onFinish={async (values) => { signIn(await api.auth.login(values)); nav("/"); return true; }}>
<ProFormText name="email" placeholder="Email" rules={[{ required: true }]} />
<ProFormText.Password name="password" placeholder="Mật khẩu" rules={[{ required: true }]} />
</LoginForm>
);
}signIn(...)stores the token; from then on every call throughuseApiClient()sends it.signOut()signs out.const { user, hasRole } = useSession()tells you who is signed in and re-renders on sign-in and sign-out. Outside React usegetUser().- The
authblock’s/loginand/registerpages show the Google button by themselves. On your own page callawait signInWith("google")fromapp/hooks.
Try each role
To try the manager or admin screens before the owner signs up, ask the agent to call the create_test_accounts tool. It makes one account per role on the deployed app (<role>@test.manh.invalid, a new password on every call). Remove them with remove_test_accounts before handover. Never promote an account with SQL.
Good to know
- No
manh/oauthand no cookie sessions. That module does not exist, and the preview in the dashboard calls the API from another origin, so cookies do not travel. A token in theAuthorizationheader works in both places. - Hiding a button in the UI only prevents mistakes. The server checks roles through
accesson every handler that writes data. - Cron, incoming email and Telegram messages do not go through
accessormiddleware.ts, and have no user in the request. - Never return
passwordHash, not even from your own API. - A page with a password field sends it only to the app’s own API. Sending it to an outside address makes
checkwarnabuse.password-external.
Next steps
- Sign-in and sign-up pages — build the sign-in page and guard pages for signed-out users.
- auth.ts — every key, the
userstable and the generated APIs. - AI and file storage — call AI and store files from a handler.