​

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:

​

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

​

Authentication Flow

​

Email/Password Authentication

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;
}

​

OAuth Authentication

// 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:

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:

​

Two-Factor Authentication (2FA)

ProductFlo supports two-factor authentication for additional security:

​

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:

{
  "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:

​

Session Properties

{
  "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