> ## Documentation Index
> Fetch the complete documentation index at: https://docs.productflo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
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:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
### Token Structure
The JWT contains the following important claims:
* `sub`: The user's unique identifier
* `exp`: Expiration time
* `iat`: Issued at time
* `tenant_id`: The current tenant context (optional)
* `role`: The user's role
* `permissions`: The user's permissions (optional)
## Token Lifecycle
User authenticates using their preferred method (email/password, OAuth, etc.)
Server generates an access token and refresh token
User includes the access token in API requests
Access token expires after a set time (1 hour by default)
User uses the refresh token to obtain a new access token
## Authentication Flow
### Email/Password Authentication
```javascript Email Login theme={null}
async function login(email, password) {
const response = await fetch('https://api.productflo.io/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password }),
credentials: 'include' // Important for cookie handling
});
if (!response.ok) {
throw new Error('Authentication failed');
}
const data = await response.json();
// Store the token securely
localStorage.setItem('accessToken', data.session.access_token);
return data;
}
```
```javascript Making Authenticated Requests theme={null}
async function fetchProfile() {
const token = localStorage.getItem('accessToken');
const response = await fetch('https://api.productflo.io/profile', {
headers: {
'Authorization': `Bearer ${token}`,
'X-Tenant-ID': currentTenantId
}
});
if (response.status === 401) {
// Token expired, need to refresh
await refreshToken();
return fetchProfile();
}
return response.json();
}
```
### OAuth Authentication
```javascript OAuth Flow theme={null}
// 1. Initiate OAuth flow
async function initiateOAuth(provider) {
const response = await fetch('https://api.productflo.io/auth/provider', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ provider }) // e.g., 'google', 'github'
});
const data = await response.json();
// Redirect user to OAuth provider
window.location.href = data.url;
}
// 2. Handle the OAuth callback
// This happens automatically when the user is redirected back to your app
// The server exchanges the code for tokens and sets the cookies/session
```
## 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:
```javascript theme={null}
async function refreshToken() {
const refreshToken = localStorage.getItem('refreshToken');
const response = await fetch('https://api.productflo.io/auth/refresh-session', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${refreshToken}`
}
});
if (!response.ok) {
// Refresh failed, user needs to log in again
redirectToLogin();
return;
}
const data = await response.json();
localStorage.setItem('accessToken', data.session.access_token);
return data;
}
```
## 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:
User enables 2FA in their account settings
User logs in with username and password
Server responds with a 2FA challenge
User submits the 2FA code from their authenticator app
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:
```json theme={null}
{
"permissions": {
"products": {
"create": true,
"read": true,
"update": true,
"delete": false
},
"teams": {
"create": false,
"read": true,
"update": false,
"delete": false
},
"files": {
"create": true,
"read": true,
"update": true,
"delete": false,
"share": false
}
}
}
```
## Session Management
ProductFlo maintains user sessions to track active users and their authentication state:
Get current session information
End the current session
### Session Properties
```json theme={null}
{
"session_id": "sess_123456789",
"user_id": "user_987654321",
"created_at": "2023-05-01T12:34:56.789Z",
"expires_at": "2023-05-02T12:34:56.789Z",
"last_active_at": "2023-05-01T15:30:45.123Z",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
"current_tenant_id": "tenant_123"
}
```
## Best Practices
When implementing authentication in your application, follow these best practices:
1. **Secure Token Storage**: Store tokens in secure HTTP-only cookies or securely in localStorage.
2. **Implement Refresh Logic**: Automatically refresh tokens when they expire.
3. **Logout Properly**: Clear all tokens and cookies when the user logs out.
4. **Handle Errors Gracefully**: Redirect to the login page when authentication fails.
5. **Use HTTPS**: Always use HTTPS to prevent token interception.
6. **Implement CSRF Protection**: Use anti-CSRF tokens for cookie-based authentication.
7. **Verify Permissions**: Check permissions before performing actions to provide appropriate UI feedback.
8. **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