Authentication overview

Learn about PocketBase authentication system and available methods

PocketBase provides a flexible authentication system for auth collections. You can enable multiple authentication methods and configure them based on your application needs.

Authentication methods

PocketBase supports several authentication methods that can be enabled independently:

Email/Password

Traditional authentication using email and password with customizable identity fields

OAuth2

Social login with 15+ providers including Google, GitHub, and Facebook

OTP

One-time password authentication via email for passwordless login

MFA

Multi-factor authentication requiring two different auth methods

Auth collection configuration

Every auth collection has an authRule that you can use to specify additional constraints applied after record authentication and before returning the auth token response to the client.

// Example: Allow only verified users to authenticate
collection.AuthRule = types.Pointer("verified = true")

// Example: Allow any auth record to authenticate
collection.AuthRule = types.Pointer("")

// Example: Disallow authentication altogether
collection.AuthRule = nil

The authRule check happens in RecordAuthResponse after the initial authentication succeeds but before the token is issued.

Authentication flow

The typical authentication flow in PocketBase follows these steps:

1. Retrieve auth methods

   Client calls GET /api/collections/{collection}/auth-methods to discover available authentication methods.

2. Authenticate user

   Client submits credentials using one of the enabled methods (password, OAuth2, or OTP).

3. Auth rule validation

   PocketBase validates the record against the collection’s authRule if configured.

4. MFA check (optional)

   If MFA is enabled and required for the user, PocketBase returns an mfaId instead of the auth token.

5. Second factor (MFA)

   If MFA is required, client authenticates again using a different method with the mfaId parameter.

6. Receive token

   PocketBase returns the auth token and record data upon successful authentication.

Auth response structure

Successful authentication returns a JSON response with the following structure:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "record": {
    "id": "RECORD_ID",
    "collectionId": "_pb_users_auth_",
    "collectionName": "users",
    "email": "[e-mail]",
    "emailVisibility": false,
    "verified": true,
    "created": "2024-01-01 00:00:00.000Z",
    "updated": "2024-01-01 00:00:00.000Z"
  },
  "meta": {}
}

The meta field contains additional provider-specific information (e.g., OAuth2 user data).

Token configuration

Auth collections have several token configurations that control the lifetime and security of various tokens:

Token Type	Purpose	Default Duration
authToken	Main authentication token	7 days (604800s)
passwordResetToken	Password reset verification	30 minutes (1800s)
emailChangeToken	Email change verification	30 minutes (1800s)
verificationToken	Email verification	3 days (259200s)
fileToken	Protected file access	3 minutes (180s)

Each token configuration includes:

• Secret: Random 50-character string for signing tokens (minimum 30 characters)
• Duration: Token validity period in seconds (minimum 10s, maximum ~3 years)

type TokenConfig struct {
    Secret   string `json:"secret,omitempty"`
    Duration int64  `json:"duration"` // in seconds
}

Auth alerts

PocketBase can send email alerts when users authenticate from new devices or locations. This feature helps users detect unauthorized access to their accounts.

type AuthAlertConfig struct {
    Enabled       bool          `json:"enabled"`
    EmailTemplate EmailTemplate `json:"emailTemplate"`
}

Auth alerts are only sent after the first successful login. The system tracks up to 5 authentication origins per user based on IP address and user agent fingerprints.

Security features

Rate limiting

All authentication endpoints include rate limiting to prevent brute force attacks:

// Example from record_auth.go
sub.POST("/auth-with-password", recordAuthWithPassword).Bind(
    collectionPathRateLimit("", "authWithPassword", "auth"),
)

Token key rotation

Every auth record has a tokenKey field that is used to sign auth tokens. When the password changes, the token key is automatically refreshed, invalidating all existing sessions:

// From record_model_auth.go
func (m *Record) RefreshTokenKey() {
    m.Set(FieldNameTokenKey+autogenerateModifier, "")
}

Email verification

Auth records track email verification status. OAuth2 and OTP authentication can automatically verify emails:

func (m *Record) Verified() bool {
    return m.GetBool(FieldNameVerified)
}

func (m *Record) SetVerified(verified bool) {
    m.Set(FieldNameVerified, verified)
}

Manage rule

The manageRule gives admin-like permissions for auth records, allowing operations like:

• Changing passwords without requiring the old password
• Directly updating the verified state
• Modifying the email without confirmation
• Ignoring email visibility settings

The manage rule is executed in addition to the Create and Update API rules. Be careful when setting this rule as it grants elevated permissions.

Common endpoints

All auth collections automatically get the following endpoints:

Method	Endpoint	Description
GET	/api/collections/{collection}/auth-methods	List available auth methods
POST	/api/collections/{collection}/auth-refresh	Refresh auth token
POST	/api/collections/{collection}/auth-with-password	Authenticate with password
POST	/api/collections/{collection}/auth-with-oauth2	Authenticate with OAuth2
POST	/api/collections/{collection}/request-otp	Request OTP code
POST	/api/collections/{collection}/auth-with-otp	Authenticate with OTP
POST	/api/collections/{collection}/request-password-reset	Request password reset
POST	/api/collections/{collection}/confirm-password-reset	Confirm password reset
POST	/api/collections/{collection}/request-verification	Request email verification
POST	/api/collections/{collection}/confirm-verification	Confirm email verification
POST	/api/collections/{collection}/request-email-change	Request email change
POST	/api/collections/{collection}/confirm-email-change	Confirm email change

Next steps

Email/Password auth

Configure traditional password authentication

OAuth2 providers

Set up social login providers

API rules

Learn about access control

MFA setup

Enable multi-factor authentication