@lowdefy/docs-content 6.1.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (285) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +5 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +43 -7
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +154 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +8 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +136 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +2 -0
  71. package/content/connections/smtp.md +3 -1
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +24 -1
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3458 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -0,0 +1,267 @@
1
+ # Auth Configuration
2
+
3
+ The `auth` section configures user authentication. Lowdefy's auth is built on [BetterAuth](https://www.better-auth.com/): sessions are database-backed, the app owns its auth UI, and roles live on organization memberships. If you are moving from the previous NextAuth-shaped config, start with the [Auth Upgrade guide](/auth-upgrade) — several keys were renamed or removed.
4
+
5
+ The `_secret` operator is evaluated over the entire `auth` section, so any value can be a secret reference.
6
+
7
+ For a login method to work you must configure **at least one mechanism** (`emailAndPassword`, `magicLink`, `emailOTP`, `phoneNumber`, an OAuth `providers` entry, or an API `strategies` entry), a `secret`, and a `database`. An `auth` block with none of these fails the build.
8
+
9
+ ## Secret
10
+
11
+ A required signing secret, given as a `_secret` reference:
12
+
13
+ ```yaml
14
+ lowdefy: 6.1.0
15
+ auth:
16
+ secret:
17
+ _secret: BETTER_AUTH_SECRET
18
+ ```
19
+
20
+ Also pin the app's canonical origin — the `url` of the current environment in [`config.environments`](/lowdefy-schema), or the `BETTER_AUTH_URL` environment variable, which wins — auth builds password-reset, magic-link and verification links, and its CSRF origin allowlist, from it. With `auth.email` configured, a production server refuses to start without it. See the [migration guide](/auth-upgrade#3-pin-the-canonical-url-with-better-auth-url).
21
+
22
+ ## Database
23
+
24
+ Sessions, users, accounts and organizations are stored through an adapter:
25
+
26
+ ```yaml
27
+ lowdefy: 6.1.0
28
+ auth:
29
+ database:
30
+ id: auth_db
31
+ type: MongoDBAuthAdapter
32
+ properties:
33
+ uri:
34
+ _secret: AUTH_DATABASE_URI
35
+ ```
36
+
37
+ See the [MongoDBAuthAdapter](/MongoDBAuthAdapter) reference. Collection names follow the `user-*` convention and are fixed by the adapter.
38
+
39
+ ## Login mechanisms
40
+
41
+ - **Email & password** — `auth.emailAndPassword` (`enabled`, `requireEmailVerification`, `minPasswordLength` (default 8), `disableSignUp`).
42
+ - **Magic link** — `auth.magicLink` (`enabled`, `expiresIn` seconds (default 300), `disableSignUp`), which needs `auth.email` (below).
43
+ - **Email one-time code** — `auth.emailOTP` (`enabled`, `otpLength` (default 6), `expiresIn` seconds (default 300), `allowedAttempts` (default 3), `disableSignUp` (default `false`)), which needs `auth.email` (below). The person is emailed a code and types it into the tab they started from, so the sign-in survives mail security that pre-fetches links, and works when the email is opened on another device.
44
+ - **OAuth providers** — `auth.providers`; see [Providers](/auth-providers).
45
+ - **Phone number** — `auth.phoneNumber` (OTP sign-in); needs a `phone.otp.send` hook to deliver the SMS.
46
+ - **Passkeys** — `auth.passkey` (`enabled`, `rpId`, `rpName`).
47
+
48
+ ```yaml
49
+ lowdefy: 6.1.0
50
+ auth:
51
+ emailAndPassword:
52
+ enabled: true
53
+ requireEmailVerification: true
54
+ ```
55
+
56
+ ## Auth email
57
+
58
+ `auth.email` references an **SMTP connection** by id — the connection owns `from`, `replyTo`, the transport and the delivery filter, and is shared by every auth email flow. There is no inline transport shape. Optionally map individual flows to your own notification templates:
59
+
60
+ ```yaml
61
+ lowdefy: 6.1.0
62
+ auth:
63
+ email:
64
+ connectionId: email # an SMTP connection in connections[]
65
+ templates: # all optional; unset → branded stock template
66
+ verifyEmail: verify-email-notification
67
+ resetPassword: reset-password-notification
68
+ magicLink: magic-link-notification
69
+ invitation: invite-notification
70
+ emailOTP: email-otp-notification
71
+ ```
72
+
73
+ ### Link and code in one email
74
+
75
+ With both `magicLink` and `emailOTP` enabled, the magic-link email also carries the one-time code, so a single email serves both paths: the person clicks the button, or types the code into the tab they asked for the link from. Nothing extra is sent — the `emailOTP` template is only used for a code-only send.
76
+
77
+ The `magicLink` template then has two more variables available: `otp` (the code) and `expiresIn` (the code's lifetime in seconds, from `auth.emailOTP.expiresIn`). The stock template renders them below the sign-in button; a template of your own can place them wherever it likes. With `emailOTP` off both are absent and the link email is unchanged.
78
+
79
+ ## Auth pages
80
+
81
+ BetterAuth ships no UI — your app owns its auth pages, and `auth.authPages` points at them. All are Lowdefy page paths:
82
+
83
+ | Key | Default | When required |
84
+ | --- | ------- | ------------- |
85
+ | `signIn` | `/login` | |
86
+ | `signUp` | `/signup` | |
87
+ | `error` | `/auth/error` | receives `?error=` code |
88
+ | `forgotPassword` | `/forgot-password` | |
89
+ | `resetPassword` | `/reset-password` | where the emailed reset link lands, with `?token=` (or `?error=INVALID_TOKEN`); the default `redirectTo` of `RequestPasswordReset` |
90
+ | `verifyEmail` | `/verify-email` | where the emailed verification link lands; receives `?error=` code when the link is invalid or expired |
91
+ | `twoFactor` | — | **required** when `twoFactor.enabled` |
92
+ | `twoFactorEnrol` | — | **required** when `twoFactor.required` |
93
+ | `acceptInvitation` | — | consumes an `?invitationId=` link |
94
+ | `magicLink` | — | landing page for the sign-in email (opt-in; see below) |
95
+
96
+ ```yaml
97
+ lowdefy: 6.1.0
98
+ auth:
99
+ authPages:
100
+ signIn: /login
101
+ signUp: /signup
102
+ error: /auth-error
103
+ ```
104
+
105
+ ### The email verification page
106
+
107
+ A verification email links to Better Auth's verify endpoint, which confirms the address and then redirects to `authPages.verifyEmail`. When the link is invalid or has expired, it redirects there with `?error=` set (`INVALID_TOKEN`, `TOKEN_EXPIRED`), so the page can offer to resend with the `SendVerificationEmail` action. A `callbackUrl` on the `SignUp` or `SendVerificationEmail` action sends that link somewhere else instead.
108
+
109
+ ### The magic link landing page
110
+
111
+ `authPages.magicLink` is opt-in, and it exists for one reason: Better Auth's magic-link verify endpoint consumes the single-use token on the **first** `GET` of the URL. Corporate mail security — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetches every link in a message at delivery time, so that first `GET` is a scanner and the person clicking arrives to `INVALID_TOKEN`.
112
+
113
+ Set the key and the sign-in email links to a page of your own instead, with the token and the callback destinations carried on its URL query. Fetching a Lowdefy page is harmless, so the token stays unspent until a real click runs [`MagicLinkVerify`](/MagicLinkVerify):
114
+
115
+ ```yaml
116
+ lowdefy: 6.1.0
117
+ auth:
118
+ magicLink:
119
+ enabled: true
120
+ authPages:
121
+ magicLink: /magic-link
122
+ pages:
123
+ public:
124
+ - magic-link
125
+ ```
126
+
127
+ ```yaml
128
+ id: magic-link
129
+ type: PageHeaderMenu
130
+ blocks:
131
+ - id: content
132
+ type: Box
133
+ blocks:
134
+ - id: title
135
+ type: Title
136
+ properties:
137
+ content: Sign in
138
+ level: 3
139
+ - id: description
140
+ type: Paragraph
141
+ properties:
142
+ content: Click the button below to finish signing in.
143
+ - id: verify_button
144
+ type: Button
145
+ properties:
146
+ title: Sign in
147
+ events:
148
+ onClick:
149
+ - id: verify
150
+ type: MagicLinkVerify
151
+ ```
152
+
153
+ The page must **not** call `MagicLinkVerify` in `onMount`, and must not auto-redirect to the verify endpoint. Scanning sandboxes that render the page and execute its JavaScript would consume the token anyway, which puts you back where you started. The protection is the click, not the page.
154
+
155
+ Leave the key unset and magic-link sign-in keeps working exactly as before, linking straight at the verify endpoint.
156
+
157
+ See [Two-Factor Authentication](/two-factor) for the two-factor pages, and the [MCP Server & OAuth](/mcp-oauth) page for `oauthProvider.consentPage` and `postLoginPage`.
158
+
159
+ ## Session
160
+
161
+ Database sessions. Length is `expiresIn` (seconds, default 604800 = 7 days); `updateAge` (default 86400) is how often an active session's expiry is refreshed:
162
+
163
+ ```yaml
164
+ lowdefy: 6.1.0
165
+ auth:
166
+ session:
167
+ expiresIn: 43200 # 12 hours in seconds
168
+ updateAge: 3600
169
+ ```
170
+
171
+ `session.cookieCache` (off by default) trades a short window of stale session reads for fewer database lookups — leave it off unless you understand the [revocation-latency trade](/two-factor#recovering-a-user-who-has-lost-their-factor).
172
+
173
+ ## Roles, organizations, and API strategies
174
+
175
+ - **Roles** — declare app role names in `auth.roles` and gate pages/endpoints with `auth.pages.roles` / `auth.api.roles`. See [Roles](/roles).
176
+ - **Organizations** — `auth.organizations.policy` (`pinned` or `tenant`) decides the whole multi-tenancy model. See [Organizations & Multi-Tenancy](/organizations).
177
+ - **API strategies** — `auth.strategies` authenticates non-session callers (server-to-server) with an `apiKey` or a `jwt`:
178
+
179
+ ```yaml
180
+ lowdefy: 6.1.0
181
+ auth:
182
+ strategies:
183
+ - id: service-key
184
+ type: apiKey
185
+ roles:
186
+ - integrations
187
+ properties:
188
+ keys:
189
+ - value:
190
+ _secret: SERVICE_API_KEY
191
+ ```
192
+
193
+ A strategy caller carries the configured `roles` and `attributes` and its `auth_method` is the strategy type. A `jwt` strategy needs exactly one of `properties.secret` or `properties.jwksUri`, and a non-empty `algorithms` allowlist (which blocks `alg: none` downgrades). Its `properties.claimMapping` copies token claims onto the caller: `id` (default `sub`), `roles`, `attributes.<name>` into `_user.attributes`, and any other name onto `_user` itself. `system` is reserved, since `_user.system` marks the stand-in caller a [`CallApi` `caller`](/lowdefy-api#running-in-one-organization) names, and the build refuses a mapping for it.
194
+
195
+ ## Captcha
196
+
197
+ `auth.captcha` protects auth endpoints with Cloudflare Turnstile. The `siteKey` is public (a plain string, never a `_secret`); the `secretKey` is a `_secret` reference. See the [Captcha block](/Captcha) for the client side.
198
+
199
+ ## Rate limiting and account linking
200
+
201
+ - `auth.rateLimit` — brute-force protection, on by default (`enabled`, `window` seconds, `max`). Sign-in and sign-up allow 3 attempts per 10 seconds, and password-reset and verification emails 3 per minute. Limits count per client address: the connection's address on a self-hosted server, or the address a trusted proxy forwarded when the app lists its proxies in [`config.trustedProxies`](/docker#behind-a-reverse-proxy). `X-Forwarded-For` from anyone else is ignored.
202
+ - `auth.account.accountLinking` — link a new OAuth sign-in to an existing account by verified email. `trustedProviders` lists providers whose email claim you trust for linking. **This is unrelated to `provider.twoFactorTrusted`** — see [Two-Factor Authentication](/two-factor#trusting-an-oauth-provider).
203
+
204
+ ## Mock User for Testing (Dev Server Only)
205
+
206
+ When developing and testing Lowdefy apps, you can bypass the login flow by configuring a mock user. This is useful for testing authenticated flows without going through OAuth login.
207
+
208
+ The mock user can be configured in three ways:
209
+
210
+ ### CLI Flag
211
+
212
+ Pass `--mock-user` to `lowdefy dev` to start the server as a mock user for that run. Supply a JSON user object to set the identity and roles, or use the bare flag for a default user with no roles:
213
+
214
+ ```bash
215
+ lowdefy dev --mock-user '{"id":"test-user","email":"test@example.com","roles":["admin"]}'
216
+ ```
217
+
218
+ The flag sets `LOWDEFY_DEV_USER` for the dev server process, so it takes precedence over `auth.dev.mockUser` in the config file.
219
+
220
+ ### Environment Variable
221
+
222
+ Set the `LOWDEFY_DEV_USER` environment variable to a JSON string containing the mock user object:
223
+
224
+ ```bash
225
+ LOWDEFY_DEV_USER='{"id":"test-user","email":"test@example.com","roles":["admin"]}'
226
+ ```
227
+
228
+ ### Config File
229
+
230
+ Add the `auth.dev.mockUser` section to your `lowdefy.yaml`:
231
+
232
+ ###### Configure a mock user for development
233
+ ```yaml
234
+ lowdefy: 6.1.0
235
+
236
+ auth:
237
+ providers:
238
+ - id: google
239
+ type: Google
240
+ properties:
241
+ clientId:
242
+ _secret: GOOGLE_CLIENT_ID
243
+ clientSecret:
244
+ _secret: GOOGLE_CLIENT_SECRET
245
+ dev:
246
+ mockUser:
247
+ id: test-user
248
+ email: test@example.com
249
+ name: Test User
250
+ roles:
251
+ - admin
252
+ ```
253
+
254
+ When a mock user is configured:
255
+ - The environment variable takes precedence over the config file if both are set
256
+ - A warning is logged at dev server startup: "Mock user active - login bypassed"
257
+ - The mock user is injected as a pre-resolved caller — its `roles` are authoritative
258
+ - It can not carry `system`, which is reserved for the stand-in caller a bound `CallApi` names; the dev server refuses a mock user that sets it
259
+ - The `_user` operator returns values from the mock user, on the server and in the browser client — the dev server serves the mock session to both
260
+ - Protected pages are accessible based on the mock user's roles
261
+ - The dev server's headless renderer (used by the AI-agent screenshot and state-inspection tools) renders as the mock user, so it can capture pages with roles the default user lacks
262
+
263
+ > **Note:** Mock users only work with the development server (`lowdefy dev`). The production server ignores mock user configuration for security.
264
+
265
+ > **Note:** `dev.mockUser` bypasses the auth engine rather than exercising it, so [auth steps](/auth-steps) (which need the running auth engine) are unavailable under a mock user.
266
+
267
+ `auth.dev` needs no auth stack behind it. An `auth` block whose only key is `dev` is not an auth configuration: it demands no login method, no `secret` and no `database`, the app builds and runs signed out in production, and in the dev server the browser is the `dev.mockUser` caller. Adding any other `auth` key declares a real auth stack, and the build then requires a mechanism, a secret and (for a login method) a database as usual.
@@ -6,6 +6,30 @@ Providers are used to configure the identity providers that will be used to auth
6
6
 
7
7
  Auth.js supports a large number of OAuth identity providers. During the OAuth flow, a user is redirected to a webpage hosted by the provider, where they usually authenticate using their credentials if not already signed in. They are then redirected back to the Lowdefy application, and the Lowdefy application interacts with the providers's API to verify the login and get the user details like name and email address.
8
8
 
9
+ ### Trusting a GenericOAuth provider's email
10
+
11
+ A `GenericOAuth` provider marks a user's email as verified only when the issuer sends the `email_verified` claim as `true`. Some issuers never send the claim, so every user they sign in stays unverified and cannot accept an organization invitation. Set `trustEmail: true` on the provider to mark every user it signs in as verified, whatever the issuer sends (also when it sends `email_verified: false`). Users it signed in before are marked verified on their next sign-in:
12
+
13
+ ```yaml
14
+ auth:
15
+ providers:
16
+ - id: company-sso
17
+ type: GenericOAuth
18
+ properties:
19
+ discoveryUrl:
20
+ _secret: SSO_DISCOVERY_URL
21
+ clientId:
22
+ _secret: SSO_CLIENT_ID
23
+ clientSecret:
24
+ _secret: SSO_CLIENT_SECRET
25
+ scopes: [openid, profile, email]
26
+ trustEmail: true
27
+ ```
28
+
29
+ Only set `trustEmail` for an issuer that controls the emails it hands out. A verified email lets a sign-in through the provider link to an existing user with the same verified email, as it would for a provider listed in `auth.account.accountLinking.trustedProviders`. That is safe when the issuer controls its emails, since the issuer's user then owns the address. To stop all linking, set `auth.account.accountLinking.enabled: false`. That applies to every provider: a user who already has an account with the same email, through another provider or email and password, can then no longer sign in through this one.
30
+
31
+ With `session.cookieCache.enabled: true`, the session from the sign-in that marks an existing user verified still reads unverified until the cache expires (`session.cookieCache.maxAge`), so accepting an invitation straight after that sign-in can still be refused.
32
+
9
33
  ## Email Provider
10
34
 
11
35
  Auth.js supports email login, where a link with a token is sent to the user's email address and the user can click on the link to log in (often called "magic links"). To use email authentication an Adapter must be configured, since the verification tokens need to be stored in a database.
@@ -0,0 +1,141 @@
1
+ # Auth Steps
2
+
3
+ Auth steps are routine steps that administer users, organizations and memberships — inviting a member, updating an app role, banning a user, creating an organization. They run **inside an `Api` or `InternalApi` endpoint routine**, not as client actions, because administering *other* people's memberships is a server operation that must be authorized against the caller, name its target organization explicitly, and be visible in a diff.
4
+
5
+ > A **client action** mutates the caller's *own* session and nothing else — `SetActiveOrganization`, `AcceptInvitation`, `LeaveOrganization`. Anything that reaches another person's membership is an auth **step** in a routine, which is what earns it the per-step authority floor below. See the [Auth Upgrade guide](/auth-upgrade#retired-client-actions) for the actions that became steps.
6
+
7
+ ```yaml
8
+ id: invite-member
9
+ type: Api
10
+ routine:
11
+ - id: invite
12
+ type: InviteMember
13
+ properties:
14
+ organizationId:
15
+ _user: organization_id
16
+ email:
17
+ _payload: email
18
+ appRoles:
19
+ _payload: roles
20
+ - ':return':
21
+ _step: invite
22
+ ```
23
+
24
+ ## The authority model
25
+
26
+ Every auth step declares, in its own code, the authority it requires — and the engine's **authority floor** enforces that declaration mechanically before the step runs. This is not optional decoration: a step with no declared authority is a build/runtime error, so an app can never expose a member mutation by forgetting a check. The reason the floor exists in one place is that most steps go adapter-direct or through BetterAuth's admin plugin, whose check reads a single deployment-wide `user.role` field and **cannot** answer "is the caller an administrator of *this* organization". For those steps, the floor is the only authorization that can express per-organization authority.
27
+
28
+ A step declares one of three **scopes**.
29
+
30
+ ### `org` — authorized against the caller's membership in the target organization
31
+
32
+ The common case. The floor:
33
+
34
+ 1. **Resolves the target organization** (see below).
35
+ 2. **Finds the caller's `member` row** in that organization and checks its role against the step's required **permissions**. The caller's authority is their membership in the *target* organization — an administrator of the team organization holds nothing in the customer organization.
36
+ 3. For steps that write the deployment-wide `user` row, additionally requires the **target user** to be a member of that organization (`targetUser`), so org authority alone can never reach a user who is not the caller's business.
37
+
38
+ Permissions map to the organization tier via BetterAuth's organization access control: `owner` and `admin` are granted the member-management permissions out of the box; `member` holds none of them. A refused caller gets a `ConfigError` naming exactly what was required.
39
+
40
+ ### `system` — caller-less, trusted runs only
41
+
42
+ A `system`-scoped step (`CreateOrganization`, `ListUsers`) has no organization to be authorized in, so a caller can never satisfy it. It runs **only** where the run itself is trusted — a caller-less system routine. Mark the step `system: true`, or run it from a system context (cron, a verified webhook, an auth hook):
43
+
44
+ ```yaml
45
+ - id: create_org
46
+ type: CreateOrganization
47
+ system: true
48
+ properties:
49
+ name:
50
+ _payload: name
51
+ slug:
52
+ _payload: slug
53
+ userId:
54
+ _payload: ownerUserId
55
+ ```
56
+
57
+ ### `caller` — acts on the caller's own records
58
+
59
+ A `caller`-scoped step (`RevokeMcpGrant`, `CreateMcpToken`, `RevokeMcpToken`, `LeaveOrganization`) acts only on rows the caller owns, so it needs no organization authority — but it is meaningless without a caller, and the system has no rows of its own. It requires a real caller and refuses `system: true`.
60
+
61
+ ### Leaving an organization from a routine
62
+
63
+ `LeaveOrganization` ends the caller's own membership of the organization named by `organizationId`. The property is required: the step has no org scope, so nothing defaults it. The organization plugin's own checks run, so a caller who is not a member there, or who is its only owner, is refused. The refusal throws with the plugin's message, which the routine catches with `:try` to branch on:
64
+
65
+ ```yaml
66
+ id: leave
67
+ type: Api
68
+ routine:
69
+ - :try:
70
+ - id: leave
71
+ type: LeaveOrganization
72
+ properties:
73
+ organizationId:
74
+ _payload: organization_id
75
+ :catch:
76
+ - :return:
77
+ refused:
78
+ message:
79
+ _error: message
80
+ # Runs only when the leave went through.
81
+ - :return:
82
+ success: true
83
+ ```
84
+
85
+ On success the step returns the member row it removed. The caller's session still names the organization they left as active, so their next request resolves unauthenticated: follow the call on the page with `SetActiveOrganization` for another organization, or with `Logout`. The `LeaveOrganization` client action leaves the session's active organization from the browser and clears it; use it when nothing else has to happen in the same request as the leave. Step and action types resolve from separate maps, so the shared name is never ambiguous.
86
+
87
+ ## `system: true` — the two doors to a caller-less run
88
+
89
+ The floor's caller requirement passes on either of two independent doors:
90
+
91
+ - a **run-level** system context (`context.system === true`) — a trusted, caller-less run such as a cron endpoint, an auth hook, or a verified webhook; or
92
+ - a **per-step** `system: true` on a single step in an otherwise user-driven run — a waiver visible in the diff, for the one privileged operation in a member-facing routine.
93
+
94
+ Either door makes the step act caller-less **as the system**, bypassing the org/permission checks. That is an explicit trust decision, not attribution — use it deliberately.
95
+
96
+ ## How the target organization is resolved
97
+
98
+ For every `org`-scoped step the floor resolves the target organization once, and the step writes into the *same* one it authorized — they cannot drift. The rule:
99
+
100
+ 1. An explicit **`organizationId`** property always wins. This is what a multi-organization admin routine passes, and it is what lets a session pinned to the team organization administer the customer organization.
101
+ 2. `ListMembers` also accepts an **`organizationSlug`**, resolved to an id here.
102
+ 3. Otherwise the **pinned** organization is the default — **but under `policy: tenant` there is no pinned organization**, so an omitted `organizationId` is a runtime error naming the fix. Under `tenant`, always pass `organizationId` explicitly.
103
+
104
+ ## `targetUser` and `selfTargetExempt`
105
+
106
+ Two refinements the floor reads from a step's declaration:
107
+
108
+ - **`targetUser`** names the property holding the id of the user being acted on. Steps that write the shared `user` row declare it, so the floor can require that user to be a member of the target organization. An absent target-user property is the step's own required-property error, not the floor's.
109
+ - **`selfTargetExempt`** lets a caller act on **their own** row without holding org authority — this is what makes `UpdateUserProfile` a self-service "save my profile" step as well as an admin one. When the named property equals the caller's own id, the org authority check is skipped.
110
+
111
+ ## Step reference
112
+
113
+ Scope, required permission, and target for every auth step. Permissions are checked against the caller's `member.role` in the target organization; `owner`/`admin` hold them by default.
114
+
115
+ | Step | Scope | Permission | Target | What it does |
116
+ | ---- | ----- | ---------- | ------ | ------------ |
117
+ | `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. |
118
+ | `CancelInvitation` | org | `invitation: [cancel]` | — | Cancel a pending invitation. |
119
+ | `ListMembers` | org | `member: [list]` | — | List members of the organization (accepts `organizationSlug`). |
120
+ | `RemoveMember` | org | `member: [delete]` | — | Remove a member from the organization. |
121
+ | `UpdateMemberRoles` | org | `member: [update]` | — | Set the membership's **app roles** (`appRoles` array; empty clears). |
122
+ | `UpdateMemberOrgRole` | org | `member: [update]` | — | Set the **org tier** (`owner`/`admin`/`member`). |
123
+ | `UpdateMemberAttributes` | org | `member: [update]` | — | Set the membership's per-organization attributes. |
124
+ | `UpdateOrganization` | org | `organization: [update]` | — | Update the organization row (name, slug, metadata). |
125
+ | `RevokeOrgMcpToken` | org | `member: [update]` | — | Switch off any [member token](/mcp-oauth#tokens-for-scripts) in the organization (`id`). |
126
+ | `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy). Self-service save is exempt. |
127
+ | `UpdateUserAttributes` | org | `user: [set-attributes]` | `userId` | Set global user attributes. |
128
+ | `BanUser` | org | `user: [ban]` | `userId` | Ban a user. |
129
+ | `UnbanUser` | org | `user: [ban]` | `userId` | Lift a ban. |
130
+ | `DeleteUser` | org | `user: [delete]` | `userId` | Delete a user. |
131
+ | `RevokeUserSessions` | org | `session: [revoke]` | `userId` | Sign a user out of all sessions. |
132
+ | `ResetUserTwoFactor` | org | `user: [reset-two-factor]` | `userId` | Clear a user's two-factor enrolment and trust-device records. |
133
+ | `RevokeUserPasskeys` | org | `user: [revoke-passkeys]` | `userId` | Remove a user's passkeys (`passkeyId` to target one). |
134
+ | `CreateOrganization` | system | — | — | Create an organization (tenant provisioning). Needs `userId`, or `name`+`slug` for creator-less provisioning. |
135
+ | `ListUsers` | system | — | — | List every user in the deployment. |
136
+ | `LeaveOrganization` | caller | — | — | End the caller's own membership of the named organization (`organizationId`, required). [Leaving from a routine](#leaving-an-organization-from-a-routine). |
137
+ | `RevokeMcpGrant` | caller | — | — | Revoke the calling assistant's own [MCP grant](/mcp-oauth#switching-organization-from-the-assistant). |
138
+ | `CreateMcpToken` | caller | — | — | Create a [member token](/mcp-oauth#tokens-for-scripts) for the caller in their active organization (`name`, `expiresInDays` or `null`). Session callers only. |
139
+ | `RevokeMcpToken` | caller | — | — | Switch off one of the caller's own [member tokens](/mcp-oauth#tokens-for-scripts) (`id`). |
140
+
141
+ The two role tiers a member carries — the `owner`/`admin`/`member` org tier and the app's own role strings — are explained in [Organizations & Multi-Tenancy](/organizations#the-owner-admin-member-tier-vs-app-roles). Recovering a user who lost their second factor is a worked routine on the [Two-Factor Authentication](/two-factor#recovering-a-user-who-has-lost-their-factor) page.
@@ -8,16 +8,21 @@ The `Login` action is used to start the user login flow. If only one OAuth provi
8
8
 
9
9
  The authorization url usually hosts a page where the user can input their credentials. After the user has logged in successfully, the user is redirected to the `/api/auth/callback/<provider_id>` route in the Lowdefy app, where the rest of the authorization code flow is completed. This URL usually needs to be configured in the identity provider's settings.
10
10
 
11
- The `callbackUrl` parameters of the Login action specify where the user is redirected after login is complete. If `callbackUrl` parameters not set, the user will return to the page from which the action was called.
11
+ The `callbackUrl` parameter of the Login action specifies where the user lands after login is complete. Three sources are consulted, in order: the `callbackUrl` param, then the `?callbackUrl=` query parameter Lowdefy sets when it redirects an unauthenticated user to the sign-in page, then the app's home page. If none resolves the action throws, rather than staying silently on the sign-in page.
12
+
13
+ In a protected app a signed-out visitor is sent to the sign-in page for every URL, present or absent, so a `404` means you are signed in — see [Page and API existence](/auth-upgrade#page-and-api-existence-is-no-longer-observable-before-you-sign-in).
14
+
15
+ To sign in without navigating at all - a login form in a modal, or an embedded panel - set `callbackUrl: false`. This is not valid for magic-link or social/OAuth sign-in, which redirect through a hop Lowdefy does not control.
12
16
 
13
17
  The parameters are:
14
18
  - `authUrl: object`:
15
19
  - `urlQuery: object`: Query parameters to set for the authorization URL.
16
- - `callbackUrl: object`:
20
+ - `callbackUrl: object | false`: Set to `false` to sign in without navigating. As an object:
17
21
  - `home: boolean`: Redirect to the home page after the login flow is complete.
18
22
  - `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
19
- - `url: string`: The URL to redirect to after the login flow is complete.
23
+ - `url: string`: The URL to redirect to after the login flow is complete. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
20
24
  - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
25
+ - `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
21
26
  - `providerId: string`: The ID of the provider that should be used for login. If not set and only one provider is configured the configured provider will be used. Else the user will be redirected to a sign in page where they can choose a provider.
22
27
 
23
28
  ## Examples
@@ -91,18 +96,165 @@ events:
91
96
  screen_hint: signup
92
97
  ```
93
98
 
99
+ ## Magic link sign-in
100
+
101
+ `Login` with `magicLink: true` emails the user a sign-in link. By default that link points straight at Better Auth's verify endpoint, which consumes the single-use token on the first `GET` of the URL.
102
+
103
+ That is a problem in corporate inboxes. Mail security products — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetch every link in a message as it is delivered, so the scanner spends the token minutes before the person clicks, and the person lands on the error page with `INVALID_TOKEN`.
104
+
105
+ Set [`auth.authPages.magicLink`](/auth-configuration#auth-pages) to a page in your app to close that gap. The email then links to your page, carrying the token and the callback destinations on its URL query, and a [`MagicLinkVerify`](/MagicLinkVerify) action on a **button click** walks to the verify endpoint. Fetching the landing page does nothing, so a scanner cannot consume the token.
106
+
107
+ ```yaml
108
+ lowdefy: {{ version }}
109
+ auth:
110
+ magicLink:
111
+ enabled: true
112
+ authPages:
113
+ magicLink: /magic-link
114
+ ```
115
+
116
+ ```yaml
117
+ id: magic-link
118
+ type: PageHeaderMenu
119
+ blocks:
120
+ - id: content
121
+ type: Box
122
+ blocks:
123
+ - id: title
124
+ type: Title
125
+ properties:
126
+ content: Sign in
127
+ level: 3
128
+ - id: description
129
+ type: Paragraph
130
+ properties:
131
+ content: Click the button below to finish signing in.
132
+ - id: verify_button
133
+ type: Button
134
+ properties:
135
+ title: Sign in
136
+ events:
137
+ onClick:
138
+ - id: verify
139
+ type: MagicLinkVerify
140
+ ```
141
+
142
+ The landing page must be reachable while signed out, so add it to `auth.pages.public`.
143
+
144
+ Do **not** run `MagicLinkVerify` in the page's `onMount`, and do not auto-redirect to the verify endpoint. Some scanning sandboxes render the page and execute its JavaScript, so an automatic verify hands the token back to the scanner and you are no better off than linking at the endpoint directly. The whole protection is that a human has to click.
145
+
146
+ The action needs no parameters: the token and the `callbackURL`, `newUserCallbackURL` and `errorCallbackURL` values are read from the landing page's own URL query, which the email put there. Pass parameters only to override them.
147
+
148
+ ## Email code sign-in
149
+
150
+ With `auth.emailOTP` enabled the app can sign a person in with a code emailed to them. Unlike a magic link, the code is typed into the tab they started from — so it survives corporate mail security that pre-fetches links (and consumes the single-use link token), and it works when the email is read on another device.
151
+
152
+ Two actions drive it:
153
+
154
+ - [`EmailOtpSend`](/EmailOtpSend) sends the code to an email address.
155
+ - [`EmailOtpVerify`](/EmailOtpVerify) signs the person in with the code they typed.
156
+
157
+ `EmailOtpVerify` lands the user through the same three sources as `Login`: the `callbackUrl` param, then the `?callbackUrl=` query, then the app's home page. `callbackUrl: false` verifies without navigating — it is a plain JSON sign-in with no redirect hop, so staying put is valid here.
158
+
159
+ ### With magic link, one email carries both
160
+
161
+ When `auth.magicLink` is enabled alongside `auth.emailOTP`, the magic-link email also carries the code, so one email serves both paths. Keep using `Login` with `magicLink: true` to send it — no change is needed — and offer `EmailOtpVerify` on the same page for people whose link does not work. `EmailOtpSend` is then only needed for a code-only page, where no link is offered at all.
162
+
163
+ ###### A sign-in page offering a code:
164
+ ```yaml
165
+ id: email-code-login
166
+ type: Box
167
+ blocks:
168
+ - id: email
169
+ type: TextInput
170
+ required: true
171
+ properties:
172
+ title: Email
173
+ - id: send_code
174
+ type: Button
175
+ properties:
176
+ title: Send code
177
+ events:
178
+ onClick:
179
+ - id: validate
180
+ type: Validate
181
+ params:
182
+ regex: ^email$
183
+ - id: send
184
+ type: EmailOtpSend
185
+ params:
186
+ email:
187
+ _state: email
188
+ - id: sent
189
+ type: DisplayMessage
190
+ params:
191
+ content: Check your email for the sign-in code.
192
+ - id: otp
193
+ type: TextInput
194
+ properties:
195
+ title: Sign-in code
196
+ - id: sign_in
197
+ type: Button
198
+ properties:
199
+ title: Sign in
200
+ events:
201
+ onClick:
202
+ - id: verify
203
+ type: EmailOtpVerify
204
+ params:
205
+ email:
206
+ _state: email
207
+ otp:
208
+ _state: otp
209
+ ```
210
+
211
+ An expired, mistyped or already-used code is the auth server rejecting the attempt, not an app fault: the action throws a `UserError`, so `onClick` `catch` actions run and the message displays, but nothing is reported to the server.
212
+
213
+ ## SMS sign-in
214
+
215
+ `PhoneNumberVerify` completes a sign-in with an SMS code, and lands the user through the same three sources as `Login`: the `callbackUrl` param, then the `?callbackUrl=` query, then the app's home page. `callbackUrl: false` verifies without navigating.
216
+
217
+ Two modes are exempt, because neither ends with the user arriving somewhere new:
218
+
219
+ - `disableSession: true` creates no session to arrive with.
220
+ - `updatePhoneNumber: true` is a signed-in user confirming a new number. They already had a session, and the confirmation usually runs in a modal a navigation would yank them out of.
221
+
222
+ ### Carrying the destination to a separate SMS form
223
+
224
+ The `?callbackUrl=` query is read from the page the action runs on, and the unauthenticated bounce puts it on `authPages.signIn`. If your SMS form lives on its own page, the link that gets the user there has to carry the parameter, or the destination falls back to the home page:
225
+
226
+ ```yaml
227
+ - id: to_phone_login
228
+ type: Link
229
+ params:
230
+ pageId: phone-login
231
+ urlQuery:
232
+ _if:
233
+ test:
234
+ _eq:
235
+ - _url_query: callbackUrl
236
+ - null
237
+ then: null
238
+ else:
239
+ callbackUrl:
240
+ _url_query: callbackUrl
241
+ ```
242
+
243
+ The `_if` is what keeps a user who reached the sign-in page directly from being sent to `/phone-login?callbackUrl=null` — `urlQuery` serialises a null value rather than dropping the key.
244
+
94
245
  ## Logout
95
246
 
96
247
  When the `Logout` action is called, the user data and authorization cookies are cleared by the app.
97
248
 
98
- The `callbackUrl` parameters of the Logout action specify where the user is redirected after logout is complete. If `callbackUrl` parameters are not set, the user will return to the page from which the action was called.
249
+ The `callbackUrl` parameter of the Logout action specifies where the user lands after logout is complete. Unlike the `Login` action it has no default and does not read the `?callbackUrl=` query: with no `callbackUrl` the page is reloaded and the server re-applies the page's auth rules, which sends a signed-out user off a protected page to the sign-in page.
99
250
 
100
251
  The parameters are:
101
252
  - `callbackUrl: object`:
102
- - `home: boolean`: Redirect to the home page after the login flow is complete.
103
- - `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
104
- - `url: string`: The URL to redirect to after the login flow is complete.
105
- - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
253
+ - `home: boolean`: Redirect to the home page after the logout flow is complete.
254
+ - `pageId: string`: The pageId of the page to redirect to after the logout flow is complete.
255
+ - `url: string`: The URL to redirect to after the logout flow is complete. An absolute URL is not `basePath`-prefixed, so it can be an external logout landing page.
256
+ - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after logout.
257
+ - `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
106
258
  - `redirect: boolean`: If set to `false` the user session will be cleared, but the page will not be reloaded.
107
259
 
108
260