# One-Time Token Plugin (/docs/plugins/one-time-token)

Generate and verify single-use token



The One-Time Token (OTT) plugin provides functionality to generate and verify secure, single-use session tokens. These are commonly used for across domains authentication.

## Installation [#installation]

<Steps>
  <Step>
    ### Add the plugin to your auth config [#add-the-plugin-to-your-auth-config]

    To use the One-Time Token plugin, add it to your auth config.

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth";
    import { oneTimeToken } from "better-auth/plugins/one-time-token"; // [!code highlight]

    export const auth = betterAuth({
        plugins: [
          oneTimeToken() // [!code highlight]
        ]
        // ... other auth config
    });
    ```
  </Step>

  <Step>
    ### Add the client plugin [#add-the-client-plugin]

    Next, include the one-time-token client plugin in your authentication client instance.

    ```ts title="auth-client.ts"
    import { createAuthClient } from "better-auth/client"
    import { oneTimeTokenClient } from "better-auth/client/plugins" // [!code highlight]

    export const authClient = createAuthClient({
        plugins: [
            oneTimeTokenClient() // [!code highlight]
        ]
    })
    ```
  </Step>
</Steps>

## Usage [#usage]

### 1. Generate a Token [#1-generate-a-token]

Generate a token using `auth.api.generateOneTimeToken` or `authClient.oneTimeToken.generate`

**Endpoint:** `GET /one-time-token/generate`

### Client Side

```ts
const { data, error } = await authClient.oneTimeToken.generate();
```

### Server Side

```ts
const data = await auth.api.generateOneTimeToken({
    // This endpoint requires session cookies.
    headers: await headers(),
});
```

### Type Definition

```ts
type generateOneTimeToken = {
}
```

This will return a `token` that is attached to the current session which can be used to verify the one-time token. By default, the token will expire in 3 minutes.

### 2. Verify the Token [#2-verify-the-token]

When the user clicks the link or submits the token, use the `auth.api.verifyOneTimeToken` or `authClient.oneTimeToken.verify` method in another API route to validate it.

**Endpoint:** `POST /one-time-token/verify`

### Client Side

```ts
const { data, error } = await authClient.oneTimeToken.verify({
    token: "some-token", // required, The token to verify.
});
```

### Server Side

```ts
const data = await auth.api.verifyOneTimeToken({
    body: {
        token: "some-token", // required, The token to verify.
    },
});
```

### Type Definition

```ts
type verifyOneTimeToken = {
    /**
     * The token to verify. 
     */
    token: string = "some-token"
}
```

This will return the session that was attached to the token.

## Options [#options]

These options can be configured when adding the `oneTimeToken` plugin:

* **`disableClientRequest`** (boolean): Optional. If `true`, the token will only be generated on the server side. Default: `false`.
* **`expiresIn`** (number): Optional. The duration for which the token is valid in minutes. Default: `3`.

```ts
oneTimeToken({
    expiresIn: 10 // 10 minutes
})
```

* **`generateToken`**: A custom token generator function that takes `session` object and a `ctx` as parameters.

* **`storeToken`**: Optional. This option allows you to configure how the token is stored in your database.

  * **`plain`**: The token is stored in plain text. (Default)
  * **`hashed`**: The token is hashed using the default hasher.
  * **`custom-hasher`**: A custom hasher function that takes a token and returns a hashed token.

<Callout type="info">
  Note: It will not affect the token that's sent, it will only affect the token stored in your database.
</Callout>

Examples:

```ts title="No hashing (default)"
oneTimeToken({
    storeToken: "plain"
})
```

```ts title="built-in hasher"
oneTimeToken({
    storeToken: "hashed"
})
```

```ts title="custom hasher"
oneTimeToken({
    storeToken: {
        type: "custom-hasher",
        hash: async (token) => {
            return myCustomHasher(token);
        }
    }
})
```