Skip to Content

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

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 /users page with Add account (name, email, first password, role).
  • providers: ["google"] adds the Sign in with Google button. The auth block 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.
  • labels names 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 on user.branchId in every handler.
  • The file holds literal values only and ends in .ts, because manh.run reads it and never runs it. app/auth.tsx is ignored and check reports config.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.

app/orders/[id:int]/status/post.ts
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 401 with code UNAUTHENTICATED; the wrong role gets 403 with code FORBIDDEN. Access is checked before the request body, so a caller with the wrong role never sees a 400 that reveals the data shape.
  • An unknown role makes check report access.unknown-role. A write API left "public" gets the warning access.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 answers 429 with code RATE_LIMITED. Change it with export const rateLimit = { max: 5, windowSec: 600 }, turn it off with export 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

app/login/page.tsx
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 through useApiClient() 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 use getUser().
  • The auth block’s /login and /register pages show the Google button by themselves. On your own page call await signInWith("google") from app/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/oauth and 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 the Authorization header works in both places.
  • Hiding a button in the UI only prevents mistakes. The server checks roles through access on every handler that writes data.
  • Cron, incoming email and Telegram messages do not go through access or middleware.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 check warn abuse.password-external.

Next steps

Last updated