Authentication
Authentication and authorization in ProductFlo
Authentication and Authorization
ProductFlo uses a comprehensive authentication and authorization system to secure your data while providing a seamless user experience. This guide explains the authentication methods, token handling, and authorization patterns used in the API.
Authentication Methods
ProductFlo supports multiple authentication methods to meet diverse security requirements:
Standard email and password authentication with optional two-factor authentication
Standard email and password authentication with optional two-factor authentication
Authentication via phone number with SMS verification
Sign in with Google, GitHub, Apple, Microsoft, or other OAuth providers
Passwordless authentication via emailed magic links
Time-based one-time passwords (TOTP) for enhanced security
JWT Authentication
All API requests (except for the authentication endpoints themselves) require a JSON Web Token (JWT) for authentication. This token is provided in the Authorization
header using the Bearer scheme:
Token Structure
The JWT contains the following important claims:
sub
: The user’s unique identifierexp
: Expiration timeiat
: Issued at timetenant_id
: The current tenant context (optional)role
: The user’s rolepermissions
: The user’s permissions (optional)
Token Lifecycle
Login
User authenticates using their preferred method (email/password, OAuth, etc.)
Token Issuance
Server generates an access token and refresh token
API Access
User includes the access token in API requests
Token Expiration
Access token expires after a set time (1 hour by default)
Token Refresh
User uses the refresh token to obtain a new access token
Authentication Flow
Email/Password Authentication
OAuth Authentication
Token Refresh
Access tokens have a limited lifetime (typically 1 hour) for security. When an access token expires, you should use the refresh token to obtain a new one:
Cookie-Based Authentication
ProductFlo also supports cookie-based authentication to simplify token management and improve security. When enabled, the server sets HTTP-only cookies containing the JWT, which are automatically included in subsequent requests:
When using cookie-based authentication, you must include credentials: 'include'
in your fetch requests to ensure cookies are sent.
Two-Factor Authentication (2FA)
ProductFlo supports two-factor authentication for additional security:
Enable 2FA
User enables 2FA in their account settings
Initial Login
User logs in with username and password
2FA Challenge
Server responds with a 2FA challenge
Submit 2FA Code
User submits the 2FA code from their authenticator app
Complete Authentication
Server verifies the code and completes authentication
Role-Based Authorization
ProductFlo uses role-based access control (RBAC) to determine what actions users can perform. Common roles include:
- Administrator: Full access to all resources
- Owner: Full access to owned resources
- Member: Limited access based on assigned permissions
- Viewer: Read-only access to specific resources
- Guest: Very limited access to shared resources
Roles are specified in the JWT and checked on each API request.
Permission Structure
Permissions in ProductFlo are structured as follows:
Session Management
ProductFlo maintains user sessions to track active users and their authentication state:
GET /auth/session
Get current session information
POST /auth/logout
End the current session
Session Properties
Best Practices
When implementing authentication in your application, follow these best practices:
-
Secure Token Storage: Store tokens in secure HTTP-only cookies or securely in localStorage.
-
Implement Refresh Logic: Automatically refresh tokens when they expire.
-
Logout Properly: Clear all tokens and cookies when the user logs out.
-
Handle Errors Gracefully: Redirect to the login page when authentication fails.
-
Use HTTPS: Always use HTTPS to prevent token interception.
-
Implement CSRF Protection: Use anti-CSRF tokens for cookie-based authentication.
-
Verify Permissions: Check permissions before performing actions to provide appropriate UI feedback.
-
Consider Session Timeouts: Implement idle timeouts for sensitive applications.
Security Considerations
ProductFlo implements several security measures to protect authentication:
- Rate Limiting: Prevents brute force attacks
- JWT Signing: Ensures tokens cannot be tampered with
- Short Token Lifetime: Limits the window of opportunity for token misuse
- HTTP-Only Cookies: Prevents JavaScript access to tokens
- Secure Cookie Flag: Ensures cookies are only sent over HTTPS
- IP Binding: Optional binding of tokens to specific IP addresses
- Audit Logging: Records all authentication events for security monitoring