docs: passwordless auth docs improvements. (#18872)

* docs: passwordless auth docs improvements. * fix: typo. * Update apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * Update apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> --------- Co-authored-by: Tyler <18113850+dshukertjr@users.noreply.github.com> Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
2026-06-20 20:16:04 +08:00 · 2023-11-14 12:46:30 +08:00
parent 1442e42b0a
commit d22e9c4e6f
5 changed files with 194 additions and 1 deletions
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -497,7 +497,15 @@ export const auth = {
      url: undefined,
      items: [
        { name: 'Email Login', url: '/guides/auth/auth-email' },
-        { name: 'Magic Link Login', url: '/guides/auth/auth-magic-link' },
+        {
+          name: 'Passwordless Login',
+          url: '/guides/auth/passwordless-login',
+          items: [
+            { name: 'Email Magic Link', url: '/guides/auth/passwordless-login/auth-magic-link' },
+            { name: 'Email OTP', url: '/guides/auth/passwordless-login/auth-email-otp' },
+            { name: 'Phone OTP', url: '/guides/auth/phone-login' },
+          ],
+        },
        {
          name: 'Phone Login',
          url: '/guides/auth/phone-login',
--- a/apps/docs/pages/guides/auth/passwordless-login.mdx
+++ b/apps/docs/pages/guides/auth/passwordless-login.mdx
@@ -0,0 +1,57 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+import { IconPanel, GlassPanel, IconMail } from 'ui'
+import Link from 'next/link'
+import { PhoneLoginsItems } from '~/components/Navigation/NavigationMenu/NavigationMenu.constants'
+
+export const meta = {
+  title: 'Passwordless Login',
+  description: 'Sign in your users without passwords via magic link email, or one-time passwords sent via email, SMS, or WhatsApp.',
+}
+
+Supabase supports various forms of passwordless authentication:
+
+- [Email Magic Link](/docs/guides/auth/passwordless-login/auth-magic-link)
+- [Email one-time password (OTP)](/docs/guides/auth/passwordless-login/auth-email-otp)
+- [SMS & WhatsApp one-time password (OTP)](/docs/guides/auth/phone-login)
+
+## Benefits
+
+There are several reasons why you might want to add passwordless login to your applications:
+
+- **Improved user experience**: Eliminating the need for users to remember and enter complex passwords can make it easier and more convenient for users to log in to your application. This can improve the overall user experience and make it more enjoyable for users to interact with your application.
+
+- **Increased security**: Passwordless login can improve the security of your application by reducing the risk of password-related security breaches, such as password reuse and weak passwords. By using alternative forms of authentication, such as one-time codes or biometric factors, you can make it more difficult for unauthorized users to access your application.
+
+- **Reduced support burden**: Passwordless login can also help reduce the support burden for your team by eliminating the need to handle password recovery flows or deal with other password-related issues. This can free up your team to focus on other important tasks and improve the efficiency of your operation.
+
+## Passwordless login options with Supabase Auth
+
+### Email based
+
+- [Email Magic Link](/docs/guides/auth/passwordless-login/auth-magic-link)
+- [Email one-time password (OTP)](/docs/guides/auth/passwordless-login/auth-email-otp)
+
+## Phone based
+
+Supabase supports [Phone Login](/docs/guides/auth/phone-login) (SMS & WhatsApp) with several communications platforms. Follow the guides below to set up a provider with Supabase Auth.
+
+<div className="grid grid-cols-12 gap-10 not-prose py-8">
+  {PhoneLoginsItems.map((item) => (
+    <Link href={`${item.url}`} key={item.name} passHref className="col-span-4">
+      <IconPanel
+        title={item.name}
+        span="col-span-6"
+        icon={item.icon}
+        isDarkMode={item.isDarkMode}
+        hasLightIcon={item.hasLightIcon}
+      >
+        {item.linkDescription}
+      </IconPanel>
+    </Link>
+))}
+
+</div>
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+
+export default Page
--- a/apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx
+++ b/apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx
@@ -0,0 +1,123 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+
+export const meta = {
+  id: 'auth-email-otp',
+  title: 'Login With Email OTP',
+  description: 'Use Supabase to authenticate your users using one-time password emails.',
+}
+
+Email one-time passwords (OTP) are a form of passwordless login where users key in a six digit code sent to their email address to log in to their accounts. By default, a user can only request an OTP once every 60 seconds and they expire after 24 hours.
+
+## Setting up Email OTP
+
+To set up email OTP for your Supabase app:
+
+- Enable the email provider in your [Supabase Project](/dashboard/project/_/auth/providers)
+- The Site URL represents the default URL that the user will be redirected to after clicking on the email signup confirmation link.
+- If a user has not signed up yet, signing in with an OTP will automatically sign up the user. To prevent users from signing up this way, you can set the `shouldCreateUser` option to `false`.
+- Navigate to the [email template settings](/dashboard/project/_/auth/templates) and modify the template to include the `{{ .Token }}` variable, for example:
+
+```html
+<h2>One time login code</h2>
+
+<p>Please enter this code: {{ .Token }}</p>
+```
+
+## Signing in a user with email OTP
+
+<Tabs
+  scrollable
+  size="small"
+  type="underlined"
+  defaultActiveId="js"
+  queryGroup="language"
+>
+<TabPanel id="js" label="JavaScript">
+When your user signs in, call [signInWithOtp()](/docs/reference/javascript/auth-signinwithotp) with their email address:
+
+```js
+const { data, error } = await supabase.auth.signInWithOtp({
+  email: 'example@email.com',
+  options: {
+    // set this to false if you do not want the user to be automatically signed up
+    shouldCreateUser: false,
+  },
+})
+```
+
+</TabPanel>
+<TabPanel id="dart" label="Dart">
+
+When your user signs in, call [signInWithOtp()](/docs/reference/dart/auth-signinwithotp) with their email address:
+
+```dart
+Future<void> signInWithEmailOtp() async {
+  final AuthResponse res = await supabase.auth.signInWithOtp(email: 'example@email.com');
+}
+```
+
+</TabPanel>
+<TabPanel id="kotlin" label="Kotlin">
+
+When your user signs in, call [sendOtpTo()](/docs/reference/kotlin/auth-signinwithotp) with their email address:
+
+```kotlin
+suspend fun signInWithEmailOtp() {
+	supabase.gotrue.sendOtpTo(Email) {
+		email = "example@email.com"
+	}
+}
+```
+
+</TabPanel>
+</Tabs>
+
+If the request was successful, you receive a response with `error: null` and a `data` object where both `user` and `session` are null. In this case you can let the user know to check their email inbox.
+
+```json
+{
+  "data": {
+    "user": null,
+    "session": null
+  },
+  "error": null
+}
+```
+
+## Verify OTP to create session
+
+Provide an input field for the user to key in the one-time code. To verify the code and complete the user's sign in, call [verifyOtp()](/docs/reference/javascript/auth-verifyotp) with their email address, the code, and `type: "email"`:
+
+```js
+const {
+  data: { session },
+  error,
+} = await supabase.auth.verifyOtp({
+  email,
+  token: '123456',
+  type: 'email',
+})
+```
+
+If successful the user will now be logged in and you should receive a valid session like:
+
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNjI3MjkxNTc3LCJzdWIiOiJmYTA2NTQ1Zi1kYmI1LTQxY2EtYjk1NC1kOGUyOTg4YzcxOTEiLCJlbWFpbCI6IiIsInBob25lIjoiNjU4NzUyMjAyOSIsImFwcF9tZXRhZGF0YSI6eyJwcm92aWRlciI6InBob25lIn0sInVzZXJfbWV0YWRhdGEiOnt9LCJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.1BqRi0NbS_yr1f6hnr4q3s1ylMR3c1vkiJ4e_N55dhM",
+  "token_type": "bearer",
+  "expires_in": 3600,
+  "refresh_token": "LSp8LglPPvf0DxGMSj-vaQ",
+  "user": {...}
+}
+```
+
+## Resources
+
+- [Supabase Account - Free Plan OK](https://supabase.com)
+- [Phone SMS & WhatsApp OTP](/docs/guides/auth/phone-login)
+- [Supabase JS Client](https://github.com/supabase/supabase-js)
+- [Supabase Flutter Client](https://github.com/supabase/supabase-flutter)
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+
+export default Page
--- a/apps/docs/pages/guides/auth/passwordless-login/auth-magic-link.mdx
+++ b/apps/docs/pages/guides/auth/passwordless-login/auth-magic-link.mdx
--- a/apps/www/lib/redirects.js
+++ b/apps/www/lib/redirects.js
@@ -2338,4 +2338,9 @@ module.exports = [
    source: '/docs/guides/functions/troubleshooting',
    destination: '/docs/guides/functions/debugging',
  },
+  {
+    permanent: true,
+    source: '/docs/guides/auth/auth-magic-link',
+    destination: '/docs/guides/auth/passwordless-login/auth-magic-link',
+  },
 ]