Skip to main content
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": "test@example.com",
    "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 TypePurposeDefault Duration
authTokenMain authentication token7 days (604800s)
passwordResetTokenPassword reset verification30 minutes (1800s)
emailChangeTokenEmail change verification30 minutes (1800s)
verificationTokenEmail verification3 days (259200s)
fileTokenProtected file access3 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:
MethodEndpointDescription
GET/api/collections/{collection}/auth-methodsList available auth methods
POST/api/collections/{collection}/auth-refreshRefresh auth token
POST/api/collections/{collection}/auth-with-passwordAuthenticate with password
POST/api/collections/{collection}/auth-with-oauth2Authenticate with OAuth2
POST/api/collections/{collection}/request-otpRequest OTP code
POST/api/collections/{collection}/auth-with-otpAuthenticate with OTP
POST/api/collections/{collection}/request-password-resetRequest password reset
POST/api/collections/{collection}/confirm-password-resetConfirm password reset
POST/api/collections/{collection}/request-verificationRequest email verification
POST/api/collections/{collection}/confirm-verificationConfirm email verification
POST/api/collections/{collection}/request-email-changeRequest email change
POST/api/collections/{collection}/confirm-email-changeConfirm 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