Authentication

💡 bkend provides various authentication methods including email, social login, and magic link.

Overview

To separate data per user and enforce permissions like "only the author can edit their own posts," you need user authentication.

The bkend authentication system is a core feature that manages Users in your project. It provides authentication features through REST API, from sign-up and sign-in to session management and multi-factor authentication (MFA).

---

Authentication Decision Tree

The following diagram guides you on which authentication method to use when calling the API.

Auth Method	Use Case	Header
JWT (User Token)	API calls on behalf of a user from the app	Authorization: Bearer {accessToken}
API Key (Publishable)	Client-side API calls	X-API-Key: pk_...
API Key (Secret)	Server-side API calls	X-API-Key: sk_...
No Auth	Public endpoints (isPublic)	None

---

Authentication Methods

bkend supports the following authentication methods.

Method	Description	Use Case
Email + Password	Traditional email/password authentication	General web/app services
Magic Link	Sends a one-time login link via email	Passwordless sign-in
Google OAuth	Social login with Google account	Quick social login
GitHub OAuth	Social login with GitHub account	Developer-oriented services

---

Authentication Flow

---

JWT Tokens

bkend uses JWT (JSON Web Token) based authentication.

Token	Purpose	Validity
Access Token	Included in auth header for API requests	Short-lived (default 1 hour)
Refresh Token	Renew Access Token when expired	Long-lived (default 7 days)

Authorization Header

Authorization: Bearer {accessToken}

⚠️ When your Access Token expires, use the Refresh Token to obtain a new Access Token. If the Refresh Token also expires, you must sign in again.

---

Required Headers

All authentication API requests require the following headers.

Header	Value	Required	Description
X-API-Key	{pk_publishable_key}	Yes	Publishable Key issued from the console
Authorization	Bearer {accessToken}	Conditional	For endpoints that require authentication

💡 You can issue a Publishable Key from the console. See API Keys for details.

---

User Roles

Users registered in a bkend project can have the following roles.

Role	Description
admin	Administrator -- full access to all data
user	Regular user -- default role
guest	Guest -- limited access

Data access permissions vary by role. See RLS Policies for details.

---

Key Features

Account Management

• Email Sign-up -- Create an account with email and password

• Email Sign-in -- Sign in with email and password

• Magic Link -- Sign in via email without a password

• Account Deletion -- Delete your account

Social Login

• Social Login Overview -- Understanding OAuth authentication flow

• Google OAuth -- Google account integration

• GitHub OAuth -- GitHub account integration

Security

• Password Management -- Password reset and change

• Email Verification -- Verify email ownership

• Session Management -- View and terminate active sessions

• Multi-Factor Authentication (MFA) -- TOTP-based two-step verification

User Management

• Account Linking -- Link multiple social accounts

• Invitation System -- Invite users via email

• User Profile -- Manage profile and avatar

• User Management -- User list, roles, and settings

Settings

• Auth Provider Configuration -- OAuth and email auth settings

• Email Templates -- Customize authentication emails

---

Next Steps

• Email Sign-up -- Implement your first authentication

• Auth & User REST API Reference -- Full API listing

• Issue API Keys in Console -- Generate API access tokens

• Hands-on Project Cookbooks -- Build real apps with authentication