mirror of
https://github.com/better-auth/better-auth.git
synced 2026-10-24 00:15:17 -05:00
97 lines
3.0 KiB
Plaintext
97 lines
3.0 KiB
Plaintext
---
|
|
title: Magic link
|
|
description: Magic link plugin
|
|
---
|
|
|
|
Magic link or email link is a way to authenticate users without a password. When a user enters their email, a link is sent to their email. When the user clicks on the link, they are authenticated.
|
|
|
|
## Installation
|
|
<Steps>
|
|
<Step>
|
|
### Add the server Plugin
|
|
|
|
Add the magic link plugin to your server:
|
|
|
|
```ts title="server.ts"
|
|
import { betterAuth } from "better-auth";
|
|
import { magicLink } from "better-auth/plugin";
|
|
|
|
export const auth = await betterAuth({
|
|
database: {
|
|
provider: "sqlite",
|
|
url: "./db.sqlite",
|
|
},
|
|
plugins: [
|
|
magicLink({
|
|
sendMagicLink: async (data: {
|
|
email: string,
|
|
token: string,
|
|
url: string
|
|
}) => {
|
|
// send email to user
|
|
}
|
|
})
|
|
]
|
|
})
|
|
```
|
|
</Step>
|
|
|
|
<Step>
|
|
### Add the client Plugin
|
|
|
|
Add the magic link plugin to your client:
|
|
|
|
```ts title="client.ts"
|
|
import { createAuthClient } from "better-auth/client";
|
|
import { magicLinkClient } from "better-auth/client/plugins";
|
|
const client = createAuthClient({
|
|
plugins: [
|
|
magicLinkClient()
|
|
]
|
|
});
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Usage
|
|
|
|
### Sign In with Magic Link
|
|
|
|
To sign in with a magic link, you need to call `signIn.magicLink` with the user's email address. The `sendMagicLink` function is called to send the magic link to the user's email.
|
|
|
|
```ts title="magic-link.ts"
|
|
const { data, error } = await client.signIn.magicLink({
|
|
email: "user@email.com",
|
|
callbackURL: "/dashboard" //redirect after successful login (optional)
|
|
});
|
|
```
|
|
|
|
### Verify Magic Link
|
|
|
|
When you send the URL generated by the `sendMagicLink` function to a user, clicking the link will authenticate them and redirect them to the `callbackURL` specified in the `signIn.magicLink` function. If an error occurs, the user will be redirected to the `callbackURL` with an error query parameter.
|
|
|
|
<Callout type="warn">
|
|
If no `callbackURL` is provided, the user will not be redirected and will see a JSON response instead. Therefore, always ensure to provide a `callbackURL` when sending the URL directly to the user.
|
|
</Callout>
|
|
|
|
If you want to handle the verification manually, (e.g, if you send the user a differnt url), you can use the `verify` function.
|
|
|
|
```ts title="magic-link.ts"
|
|
const { data, error } = await client.magicLink.verify({
|
|
query: {
|
|
token
|
|
}
|
|
});
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
**sendMagicLink**: The `sendMagicLink` function is called when a user requests a magic link. It takes an object with the following properties:
|
|
|
|
- `email`: The email address of the user.
|
|
- `url`: The url to be sent to the user. This url contains the token.
|
|
- `token`: The token if you want to send the token with custom url.
|
|
|
|
**expiresIn**: specifies the time in seconds after which the magic link will expire. The default value is `300` seconds (5 minutes).
|
|
|