Authentication & Authorization

Authentication Methods

flow8 supports three distinct authentication mechanisms, each suited for different client types and use cases.

1. Session & Cookie Authentication

Mechanism:

1. User submits username and password to /api/v1/auth/login
2. Server verifies password against bcrypt hash (cost=12)
3. Server generates HTTP-only session cookie with random session ID
4. Client includes cookie in subsequent requests
5. Server validates session TTL and user status

Session configuration:

config/config.yml

session:
  ttl_hours: 1              # Session lifetime
  cookie_secure: true       # HTTPS only
  cookie_http_only: true    # JavaScript cannot access
  cookie_same_site: strict  # CSRF protection
  cookie_domain: ""         # Auto-detect from Host header
  cookie_path: "/"

Environment overrides:

SESSION_TTL_HOURS=2
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_HTTP_ONLY=true
SESSION_COOKIE_SAME_SITE=strict

Security properties:

• bcrypt cost=12: ~100-200ms to hash (prevents brute force)
• HTTP-only flag: Prevents XSS attacks from stealing session
• Secure flag: Prevents transmission over unencrypted HTTP
• SameSite=Strict: Prevents CSRF attacks
• Random session ID: 32-byte cryptographically random

Flow:

User                          Server
  │                             │
  │─── POST /auth/login ───────→│
  │    (username, password)     │
  │                             ├─ Verify username exists
  │                             ├─ Verify bcrypt(password)
  │                             ├─ Generate session ID
  │                             ├─ Store session with TTL
  │←── Set-Cookie: sid=... ────│
  │                             │
  │─── GET /api/flows ────────→│ (Include Cookie: sid=...)
  │                             ├─ Lookup session by ID
  │                             ├─ Check TTL not expired
  │                             ├─ Return flows for user's company
  │←── Flows ──────────────────│

Cookie header example:

Set-Cookie: sid=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6;
            Path=/;
            Domain=.flow8.local;
            HttpOnly;
            Secure;
            SameSite=Strict;
            Max-Age=3600

2. API Key Authentication (JWT)

Mechanism:

1. Administrator creates API key via /api/v1/admin/api-keys
2. Server generates JWT with claims (user_id, company_id, key_id, scope)
3. JWT is signed with HS256 using server secret
4. Client includes JWT in Authorization: Bearer <token> header
5. Server validates signature and claims

API Key creation:

POST /api/v1/admin/api-keys
{
  "name": "deployment-automation",
  "user_id": "...",
  "company_id": "...",
  "scope": "api,mcp",        # Comma-separated scopes
  "expires_at": "2027-04-04T10:00:00Z"
}

Response:
{
  "id": "key_123...",
  "token": "eyJhbGciOiJIUzI1NiIs..."  # JWT (returned once only)
}

JWT structure (HS256):

Header:
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:
{
  "sub": "user_123",           # User ID
  "iss": "flow8",              # Issuer
  "aud": ["api"],              # Audience
  "company_id": "company_456", # Multi-tenancy
  "key_id": "key_123",         # For key rotation/revocation
  "scope": ["api", "mcp"],     # Requested scopes
  "iat": 1712244000,           # Issued at
  "exp": 1743780000            # Expiration
}

Signature:
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret_key
)

Scope system:

Scope	Grants	Restrictions
api	Full REST API access	Read/write flows, plays, configs
mcp	Model Context Protocol access	Limited to MCP tools (flow CRUD for AI agents)
read	Read-only API access	GET endpoints only
flow:execute	Execute flows	Cannot create/edit flows

Security properties:

• HS256: Symmetric signature (only server can mint tokens)
• Key ID in claim: Enables key rotation without breaking all tokens
• Per-scope restrictions: Limits blast radius of compromised key
• TTL enforced: Tokens expire and must be refreshed
• Revocation: Listing key as revoked invalidates all tokens with that key_id

Usage example:

# Create key
API_KEY=$(curl -X POST http://localhost:4454/api/v1/admin/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"name":"ci-cd","scope":"api"}' | jq -r .token)

# Use key to call API
curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:4454/api/v1/flows

3. OAuth2 Authentication (Microsoft/Office 365)

Mechanism:

1. User clicks “Login with Office 365” on sign-in page
2. Browser redirects to Microsoft login
3. User authenticates with their corporate identity
4. Microsoft redirects back to flow8 with authorization code
5. flow8 exchanges code for access token (backend)
6. flow8 looks up or auto-creates user in database
7. Session cookie is created
8. User is logged in

Configuration:

config/config.yml

oauth2:
  microsoft:
    client_id: "550e8400-e29b-41d4-a716-446655440000"
    client_secret: "[encrypted]"              # Encrypted in config/secrets
    redirect_uri: "https://app.flow8.io/auth/callback"
    scopes: ["openid", "profile", "email"]
    auto_create_users: true                   # Create user on first login
    auto_assign_company: "company_123"        # Assign to company if not in any

Environment variables:

MICROSOFT_CLIENT_ID=550e8400-e29b-41d4-a716-446655440000
MICROSOFT_CLIENT_SECRET=...
MICROSOFT_REDIRECT_URI=https://app.flow8.io/auth/callback
OAUTH2_AUTO_CREATE_USERS=true

OAuth2 flow diagram:

User                    Browser                flow8              Microsoft
  │                       │                     │                    │
  │─── Click Login ──────→│                     │                    │
  │                       │─ Redirect ─────────→│                    │
  │                       │  /authorize?        │                    │
  │                       │   client_id=...     │                    │
  │                       │   redirect_uri=...  │─ Redirect ────────→│
  │                       │                     │  /authorize?...    │
  │◄─────────────────────────────────────────────────────────────────│
  │              (Microsoft login page)
  │─── Submit creds ─────→│ (Microsoft handles)
  │                       │
  │◄──────────────────────┤─ Redirect back ────│
  │  with code=...        │  /callback?code=..←│
  │                       │
  │                       │──Post /token ─────→│
  │                       │  (client_id,       │
  │                       │   client_secret,   │
  │                       │   code)            │
  │                       │                    │
  │                       │←─ Access token ────│
  │                       │
  │                       │──Get /userinfo───→ │
  │                       │   (access_token)   │
  │                       │                    │
  │                       │←─ User info ───────│
  │                       │   (email, name)    │
  │                       │
  │                       │◄─ Set-Cookie ─────│
  │◄──────────────────────────────────────────│
  │     (session created)

Access token storage (DBLink):

type DBLink struct {
    ID                  primitive.ObjectID
    UserID              primitive.ObjectID
    CompanyID           primitive.ObjectID
    IntegrationType     string          // "microsoft", "google", "slack", etc.
    AccessToken         string          // [encrypted]
    RefreshToken        string          // [encrypted]
    TokenExpiry         time.Time
    Scopes              []string        // Requested scopes
    ProviderUserID      string          // Unique ID from provider
    ProviderUserEmail   string          // Email from provider
    CreatedAt           time.Time
    UpdatedAt           time.Time
}

Security properties:

• Code exchange: Server-side (token never exposed to browser)
• Token encryption: Stored encrypted in MongoDB
• Token refresh: Automatic refresh before expiry
• Scopes: Minimal scopes requested (openid, profile, email)
• PKCE: Optional (recommended for high-security deployments)

Authorization & RBAC

Company-Level Isolation

Every flow8 entity is scoped to a company_id:

type DBFlow struct {
    CompanyID primitive.ObjectID
    // ...
}

type DBUser struct {
    CompanyID primitive.ObjectID  // User can belong to multiple companies
    // ...
}

type DBAuditLog struct {
    CompanyID primitive.ObjectID
    // ...
}

All database queries are automatically filtered:

// Middleware attaches company context from session/token
ctx := r.Context()
companyID := ctx.Value("company_id")

// All queries include company filter
flows, _ := s.db.Collection("flows").Find(ctx, bson.M{
    "company_id": companyID,  // Automatic filter
})

A user in multiple companies must specify which company they’re accessing:

POST /api/v1/auth/switch-company
{
  "company_id": "company_xyz"
}

Role-Based Access Control (RBAC)

Each user has a role per company:

Role	Permissions	Use Case
admin	Create users, assign roles, manage OAuth2, configure system	IT administrator
flow_editor	Create, edit, deploy flows	Flow developer
flow_executor	Execute flows, view results	End user, automation consumer
audit_viewer	Read audit logs, view user activity	Compliance officer
integration_manager	Manage OAuth2 links, API credentials	Integration specialist
analytics_viewer	View flow metrics, performance analytics	Manager
viewer	Read-only access to flows and results	Stakeholder
none	No access (default)	Placeholder

Example user roles:

{
  "_id": "user_123",
  "email": "alice@company.com",
  "company_roles": [
    {
      "company_id": "company_a",
      "role": "admin"
    },
    {
      "company_id": "company_b",
      "role": "flow_editor"
    }
  ]
}

Permission matrix:

Resource	View	Create	Edit	Delete	Execute
Flows	viewer+	flow_editor+	flow_editor+	admin	flow_executor+
Plays	viewer+	N/A	N/A	admin	flow_executor (own)
Audit Logs	audit_viewer+	N/A	N/A	N/A	N/A
OAuth2 Links	admin	integration_mgr+	integration_mgr+	admin	N/A
System Config	admin	N/A	admin	N/A	N/A

Entity-Level Access Control (DBAccess)

For fine-grained control beyond roles, use the access_grants collection:

type DBAccess struct {
    ID              primitive.ObjectID
    CompanyID       primitive.ObjectID
    ResourceType    string              // "flow", "flow_group", "integration"
    ResourceID      primitive.ObjectID  // Flow ID, group ID, etc.
    GrantType       string              // "user" or "group"
    GranteeID       primitive.ObjectID  // User ID or group ID
    Permissions     []string            // ["read", "execute", "edit", "delete"]
    CreatedBy       primitive.ObjectID  // Creator user ID
    CreatedAt       time.Time
}

Example: Grant editor access to a specific flow:

POST /api/v1/access/grant
{
  "resource_type": "flow",
  "resource_id": "flow_456",
  "grantee_id": "user_789",
  "grant_type": "user",
  "permissions": ["read", "execute", "edit"]
}

Access evaluation:

if user has admin role → ALLOW
if user is flow creator → ALLOW
if DBAccess grant exists for user+flow → ALLOW if permissions match
otherwise → DENY

Multi-Company User Support

A user can be assigned to multiple companies with different roles:

# Alice is admin in company A, flow_executor in company B
curl -X POST http://localhost:4454/api/v1/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "email": "alice@company.com",
    "roles": [
      {"company_id": "company_a", "role": "admin"},
      {"company_id": "company_b", "role": "flow_executor"}
    ]
  }'

# Later, Alice switches to company B
curl -X POST http://localhost:4454/api/v1/auth/switch-company \
  -H "Authorization: Bearer $SESSION_COOKIE" \
  -d '{"company_id": "company_b"}'

# Now Alice can only access company B data

Session context (stored in cookie/JWT) tracks current company:

type SessionContext struct {
    UserID    primitive.ObjectID
    CompanyID primitive.ObjectID  // Current company
    Roles     []string            // Roles in current company
    Scopes    []string            // (for JWT)
}

API Key Scopes

API keys can be restricted to specific operations via scopes:

Scope Definitions

Scope	Grants	Restrictions
api	Full REST API	All endpoints
api:read	Read-only API	GET endpoints only
api:flows	Flow management	POST /flows, PUT /flows/:id
api:plays	Play execution	POST /plays, GET /plays
mcp	MCP tools	Flow management for AI agents
webhooks	Webhook management	POST /webhooks, PUT /webhooks/:id
admin	Admin operations	User management, system config

Example: Create read-only API key for metrics:

POST /api/v1/admin/api-keys
{
  "name": "metrics-export",
  "scope": "api:read",
  "expires_at": "2027-04-04T00:00:00Z"
}

Scope enforcement in middleware:

func (m *AuthMiddleware) Validate(token *jwt.Token) error {
    claims := token.Claims.(jwt.MapClaims)
    requiredScope := m.getRequiredScope(r.URL.Path)  // e.g., "api:flows" for POST /flows
    grantedScopes := parseScopes(claims["scope"])

    if !contains(grantedScopes, requiredScope) {
        return errors.New("insufficient scope")
    }
}

Session Management

Session Lifecycle

┌─────────────────────────────────────────────────────┐
│                   SESSION CREATION                   │
│  POST /auth/login → verify password → issue cookie  │
└──────────────────────┬────────────────────────────┘
                       │ TTL (1 hour default)
┌──────────────────────▼────────────────────────────┐
│                   ACTIVE SESSION                   │
│  User makes requests with cookie, TTL refreshed    │
└──────────────────────┬────────────────────────────┘
                       │ TTL expires
┌──────────────────────▼────────────────────────────┐
│                   SESSION EXPIRED                  │
│  Cookie invalid, user redirected to login          │
└─────────────────────────────────────────────────┘

Session Storage

Sessions stored in MongoDB with TTL index:

type DBSession struct {
    ID          primitive.ObjectID
    UserID      primitive.ObjectID
    CompanyID   primitive.ObjectID
    SessionID   string              // Random
    CreatedAt   time.Time
    ExpiresAt   time.Time           // TTL index
    LastActivity time.Time           // For activity tracking
}

// MongoDB TTL index
db.sessions.createIndex({ "expires_at": 1 }, { expireAfterSeconds: 0 })

Sessions are deleted automatically by MongoDB after expiry.

Token Revocation

API Key Revocation

DELETE /api/v1/admin/api-keys/:key_id

Listing revoked key IDs in a cache prevents their use:

type RevokedKeys struct {
    KeyID     string
    RevokedAt time.Time
}

// Check during validation
if isInRevokedList(claims["key_id"]) {
    return errors.New("token revoked")
}

Session Logout

POST /auth/logout

Deletes the session from MongoDB:

db.sessions.deleteOne({ "session_id": sessionID })

Cookie is also cleared from browser.

Best Practices

1. Use OAuth2 for enterprise: Integrates with Azure AD, enforces MFA
2. Rotate API keys quarterly: Limit exposure window
3. Use short-lived tokens: Set expires_at to 24 hours maximum
4. Monitor failed auth: Alert on multiple failed login attempts
5. Use entity-level access for sensitive flows: Don’t rely on role alone
6. Enable audit logging: Track all auth events for compliance
7. Implement rate limiting: Prevent brute force attacks (e.g., max 5 login attempts per minute)