Authentication Overview

Authentication is a critical part of any application. FrogBot provides a secure, portable way to manage user accounts out of the box. FrogBot Authentication is designed for both the Admin Panel and your own external applications, eliminating the need for paid third-party platforms and services. FrogBot does not require you to define a users collection. If no auth collection exists, FrogBot supplies its default users collection. If exactly one auth collection exists, FrogBot uses it as the owner relationship for chat chats regardless of its slug. With multiple auth collections, set admin.user to choose one. Here are some common use cases of Authentication in your own applications:

Customer accounts for an e-commerce app
User accounts for a SaaS product
P2P apps or social sites where users need to log in and manage their profiles
Online games where players need to track their progress over time

When Authentication is enabled on a Collection, FrogBot injects all necessary functionality to support the entire user flow. This includes all auth-related operations like account creation, logging in and out, and resetting passwords, all auth-related emails like email verification and password reset, as well as any necessary UI to manage users from the Admin Panel. To enable Authentication on a Collection, use the auth property in the Collection Config. Add auth.signIn for OAuth sign-in.

import type { CollectionConfig } from 'frogbot'

export const Users: CollectionConfig = {
  // ...
  auth: true,
}

Authentication Admin Panel functionality

Admin Panel screenshot depicting an Admins Collection with Auth enabled

Config Options

Any Collection can opt-in to supporting Authentication. Once enabled, each Document that is created within the Collection can be thought of as a “user”. This enables a complete authentication workflow on your Collection, such as logging in and out, resetting their password, and more.

Note: By default, FrogBot provides an auth-enabled User Collection which is used to access the Admin Panel.

To enable Authentication on a Collection, use the auth property in the Collection Config:

import type { CollectionConfig } from 'frogbot'

export const Admins: CollectionConfig = {
  // ...
  auth: {
    tokenExpiration: 7200, // How many seconds to keep the user logged in
    verify: true, // Require email verification before being allowed to authenticate
    maxLoginAttempts: 5, // Automatically lock a user out after X amount of failed logins
    lockTime: 600 * 1000, // Time period to allow the max login attempts
    // More options are available
  },
}

Tip: For default auth behavior, set auth: true. This is a good starting point for most applications.

Note: Auth-enabled Collections will be automatically injected with the hash, salt, and email fields. See field names for reserved-name guidance.

The following options are available:

Option	Type	Default	Description
`cookies`	`{ secure?: boolean; sameSite?: 'lax' \| 'strict' \| 'none'; domain?: string }`	`{ sameSite: 'lax', secure: false }`	Options for the auth cookie. More details.
`depth`	`number`	`0`	How many levels deep a `user` document should be populated when creating the JWT and binding the `user` to the `req`. Change it only when you must, as this will affect performance.
`disableLocalStrategy`	`true \| { enableFields?: true; optionalPassword?: true }`	—	Advanced - turns off email and password login. Only use it when a custom strategy or sign-in method replaces it. More details.
`forgotPassword`	`{ expiration?: number; minRequestInterval?: number; generateEmailHTML?: AuthEmailTemplate; generateEmailSubject?: AuthEmailTemplate }`	`{ expiration: 3600000, minRequestInterval: 15000 }`	Customizes the `forgotPassword` operation: token lifetime, the minimum time between reset emails, and the email’s HTML and subject. More details.
`lockTime`	`number`	`600000`	Time, in milliseconds, that a user stays locked after failing to log in more times than `maxLoginAttempts` allows.
`loginWithUsername`	`boolean \| LoginWithUsernameOptions`	`false`	Lets users log in with a username. More details.
`maxLoginAttempts`	`number`	`5`	Failed logins allowed before the user is locked out for `lockTime`. Set to `0` to disable.
`removeTokenFromResponses`	`true`	—	Leaves the token out of the bodies of auth responses such as login, refresh, and reset password. The auth cookie is still set.
`strategies`	`AuthStrategy[]`	`[]`	Advanced - custom authentication strategies for this collection. More details.
`signIn`	`SignInMethod[]`	—	OAuth piece instances that provide interactive login for this collection. More details.
`tokenExpiration`	`number`	`7200`	How long, in seconds, a login lasts. JWTs and HTTP-only cookies expire at the same time.
`useSessions`	`boolean`	`true`	Stores a session for each login, so logging out or resetting a password ends it. Set to `false` to use stateless JWTs instead.
`verify`	`boolean \| { generateEmailHTML?: AuthEmailTemplate; generateEmailSubject?: AuthEmailTemplate }`	`false`	Requires users to verify their email before they can log in. More details.

AuthEmailTemplate is ({ token, user }) => string | Promise<string>.

Option	Type	Default	Description
`secure`	`boolean`	`false`	Sends the cookie only over HTTPS. Set it to `true` in production, and whenever `sameSite` is `'none'`.
`sameSite`	`'lax' \| 'strict' \| 'none'`	`'lax'`	The cookie’s `SameSite` attribute. Use `'none'` with `secure: true` when your frontend is on another site.
`domain`	`string`	Current host	Domain the cookie is valid for, such as `.example.com` to share it with subdomains. See Cookies.

Disable local strategy

Set disableLocalStrategy: true to remove the email, password, and lockout fields, and to make the login, forgot password, reset password, unlock, and email verification operations fail. Pass an object to change what is kept.

Option	Type	Default	Description
`enableFields`	`true`	—	Keeps the auth fields, such as `email` and `password`, on the collection, so the database schema and generated types don’t change.
`optionalPassword`	`true`	—	Accepted by the type, but has no effect.

You can allow users to login with their username instead of their email address by setting the loginWithUsername property to true. Example:

{
  slug: 'customers',
  auth: {
    loginWithUsername: true,
  },
}

Or, you can pass an object with additional options:

{
  slug: 'customers',
  auth: {
    loginWithUsername: {
      allowEmailLogin: true, // default: false
      requireEmail: false, // default: false
    },
  },
}

Option	Type	Default	Description
`allowEmailLogin`	`boolean`	`false`	When `true`, users can log in with either their username or email address. When `false`, users can only log in with their username.
`requireEmail`	`boolean`	`false`	When `true`, an email address is required when creating a new user.
`requireUsername`	`boolean`	`true`	When `true`, a username is required when creating a new user. It can be `false` only when `allowEmailLogin` is `true`.

For testing and demo purposes you may want to skip forcing the user to login in order to access your application. Typically, all users should be required to login, however, you can speed up local development time by enabling auto-login. To enable auto-login, set the autoLogin property in the FrogBot Config:

import { buildConfig } from 'frogbot'

export default buildConfig({
  // ...
  admin: {
    autoLogin:
      process.env.NODE_ENV === 'development'
        ? {
            email: 'test@example.com',
            password: 'test',
            prefillOnly: true,
          }
        : false,
  },
})

Warning: The recommended way to use this feature is behind an Environment Variable. This will ensure it is disabled in production.

autoLogin defaults to false. To turn it on, pass an object:

Option	Type	Default	Description
`email`	`string`	—	Email address of the user to log in as. Set `email` or `username`.
`username`	`string`	—	Username of the user to log in as, for collections with `loginWithUsername`. Used when `email` isn’t set.
`password`	`string`	—	The user’s password. Only used with `prefillOnly`, to fill in the login form.
`prefillOnly`	`boolean`	`false`	Fills in the login form instead of logging in, so the user still clicks the login button.

Without prefillOnly, every request that has no valid login token is authenticated as this user: the admin panel, REST and GraphQL requests, and frogbot.auth().

Auto-Refresh

Turning this property on will allow users to stay logged in indefinitely while their browser is open and on the admin panel, by automatically refreshing their authentication token before it expires. To enable auto-refresh for user tokens, set autoRefresh: true in the FrogBot Config. It defaults to false, which shows a prompt to stay logged in before the token expires:

import { buildConfig } from 'frogbot'

export default buildConfig({
  // ...
  admin: {
    autoRefresh: true,
  },
})

Operations

All auth-related operations are available via FrogBot’s REST, Local, and GraphQL APIs. These operations are automatically added to your Collection when you enable Authentication. More details.

Strategies

Out of the box FrogBot ships with three powerful Authentication strategies:

Each of these strategies can work together or independently. You can also create your own custom strategies to fit your specific needs. More details.

HTTP-Only Cookies

HTTP-only cookies are a highly secure method of storing identifiable data on a user’s device so that FrogBot can automatically recognize a returning user until their cookie expires. They are totally protected from common XSS attacks and cannot be read by JavaScript in the browser, unlike JWT’s. More details.

JSON Web Tokens

JWT (JSON Web Tokens) can also be utilized to perform authentication. Tokens are generated on login, refresh and me operations and can be attached to future requests to authenticate users. More details.

API Keys

API keys come from the API keys plugin. They’re particularly useful when you want to authenticate against FrogBot from a third-party service. More details.

Custom Strategies

There are cases where these may not be enough for your application. FrogBot is extendable by design so you can wire up your own strategy when you need to. More details.

Access Control

Default auth fields including email, username, and password can be overridden by defining a custom field with the same name in your collection config. This allows you to customize the field — including access control — while preserving the underlying auth functionality. For example, you might want to restrict the email field from being updated once it is created, or only allow it to be read by certain user roles. You can achieve this by redefining the field and setting access rules accordingly. Here’s an example of how to restrict access to default auth fields:

import type { CollectionConfig } from 'frogbot'

export const Auth: CollectionConfig = {
  slug: 'users',
  auth: true,
  fields: [
    {
      name: 'email', // or 'username'
      type: 'text',
      access: {
        create: () => true,
        read: () => false,
        update: () => false,
      },
    },
    {
      name: 'password', // this will be applied to all password-related fields including new password, confirm password.
      type: 'text',
      hidden: true, // needed only for the password field to prevent duplication in the Admin panel
      access: {
        update: () => false,
      },
    },
  ],
}

Note:

Access functions will apply across the application — I.e. if read access is disabled on email, it will not appear in the Admin panel UI or API.
Restricting read on the email or username disables the Unlock action in the Admin panel as this function requires access to a user-identifying field.
When overriding the password field, you may need to include hidden: true to prevent duplicate fields being displayed in the Admin panel.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Authentication Overview

Config Options

Disable local strategy

Auto-Refresh

Operations

Strategies

HTTP-Only Cookies

JSON Web Tokens

API Keys

Custom Strategies

Access Control

​Config Options

​Cookie options

​Disable local strategy

​Login With Username

​Auto-Login

​Auto-Refresh

​Operations

​Strategies

​HTTP-Only Cookies

​JSON Web Tokens

​API Keys

​Custom Strategies

​Access Control

Config Options

Cookie options

Disable local strategy

Login With Username

Auto-Login

Auto-Refresh

Operations

Strategies

HTTP-Only Cookies

JSON Web Tokens

API Keys

Custom Strategies

Access Control