Authentication & Authorization

Comprehensive security model for user authentication and resource authorization in Twig AI.

Authentication

Verify user identity through multiple methods.

Supported Methods

1. Email/Password

• Standard username/password
• Secure password hashing (bcrypt)
• Password requirements: 8+ characters, special chars
• Account lockout after failed attempts

2. Single Sign-On (SSO)

• SAML 2.0
• OAuth 2.0 / OpenID Connect
• Azure AD / Microsoft Entra
• Google Workspace
• Okta, OneLogin, custom IdPs

3. Multi-Factor Authentication (MFA)

• Time-based OTP (TOTP)
• SMS codes
• Authenticator apps
• Required for admin roles (recommended)

4. API Keys

• Programmatic access
• Bearer token authentication
• Scoped permissions
• Rotatable

Authorization

Control what authenticated users can do.

Role-Based Access Control (RBAC)

Four primary roles:

• Super Admin: Complete control
• Admin: Day-to-day management
• Manager: Team-level control
• User: Standard access

See User Permissions & Roles for complete matrix.

Resource-Level Permissions

Control access to specific resources:

Agents:

• View: Can see agent exists
• Use: Can query agent
• Edit: Can modify configuration
• Manage: Full control

Data Sources:

• View: Can see source
• Connect: Can add to agents
• Edit: Can modify settings
• Process: Can trigger sync

Groups:

• Member: Part of group
• Manager: Can add/remove members
• Admin: Full group control

Attribute-Based Access Control (ABAC)

Enterprise feature for fine-grained control:

{
  "policy": {
    "resource": "agent:agent-123",
    "action": "use",
    "conditions": [
      {"user.role": "manager"},
      {"user.department": "support"},
      {"time.hour": {">=": 9, "<=": 17}}
    ]
  }
}

Security Features

Session Management

Settings:

{
  "session": {
    "timeout": 28800,        // 8 hours
    "renewOnActivity": true,
    "maxConcurrent": 3,      // Max 3 sessions per user
    "enforceIPBinding": false
  }
}

Security Controls:

• Secure session cookies (httpOnly, secure, sameSite)
• Session invalidation on logout
• Automatic timeout after inactivity
• Concurrent session limits

Token Security

Access Tokens:

• Short-lived (1 hour default)
• JWT format with signature
• Includes user ID, org ID, roles
• Cannot be modified

Refresh Tokens:

• Long-lived (30 days)
• Securely stored
• Can be revoked
• Used to obtain new access tokens

Password Security

Requirements:

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Storage:

• Bcrypt hashing (cost factor: 12)
• Salted per user
• Never stored in plain text
• Never logged

API Key Security

Generation:

• Cryptographically random
• Minimum 32 characters
• Prefix indicates type (sk_live_, sk_test_)

Storage:

• Hashed in database
• Only shown once at creation
• Cannot be retrieved later

Permissions:

• Scoped to specific operations
• Can be revoked instantly
• Audit log of all usage

Access Control Patterns

Least Privilege

Example:

Support Agent User:
✅ Can use support agents
✅ Can view their interactions
❌ Cannot create agents
❌ Cannot view all users
❌ Cannot access billing

Reasoning: Only what's needed for their job

Separation of Duties

Example:

Agent Creator:
✅ Can create and configure agents
❌ Cannot deploy to production

Production Approver:
❌ Cannot create agents
✅ Can deploy to production

Reasoning: Prevents unilateral changes

Time-Based Access

{
  "accessControl": {
    "allowedHours": {
      "start": 9,
      "end": 17,
      "timezone": "America/New_York"
    },
    "allowedDays": [1, 2, 3, 4, 5] // Mon-Fri
  }
}

Audit Logging

All authentication and authorization events are logged:

Logged Events:

• Login attempts (success/failure)
• Logout events
• Role changes
• Permission grants/revokes
• API key creation/deletion
• Resource access attempts
• Failed authorization attempts

Log Format:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "event": "LOGIN_SUCCESS",
  "userId": "user-123",
  "email": "user@example.com",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "mfaUsed": true,
  "sessionId": "session-456"
}

Retention: 90 days (configurable for Enterprise)

Security Best Practices

1. Enable MFA

✅ Require for admins ✅ Encourage for all users ✅ Use authenticator apps (more secure than SMS) ❌ Don't rely solely on passwords

2. Regular Access Reviews

✅ Quarterly user access reviews ✅ Remove inactive accounts ✅ Verify role assignments ✅ Audit API key usage ❌ Don't grant permanent access without review

3. Principle of Least Privilege

✅ Grant minimum necessary permissions ✅ Use groups for management ✅ Time-limit contractor access ❌ Don't make everyone admin

4. Monitor Failed Attempts

✅ Alert on repeated failures ✅ Automatic account lockout ✅ Investigate suspicious patterns ❌ Don't ignore security logs

Troubleshooting

Cannot Login

Check:

1. Correct email/password
2. Account is active
3. MFA code is correct
4. Not locked out
5. SSO is configured properly

Unauthorized API Requests

Check:

1. API key format correct
2. Key hasn't been revoked
3. Key has required scopes
4. Request to correct endpoint
5. Organization ID matches

Permission Denied

Check:

1. User has required role
2. Resource exists and user has access
3. Group memberships are correct
4. No time-based restrictions apply

Next Steps

• SSO Integration - Enterprise authentication
• Data Privacy - Data protection
• Security Best Practices - Harden security
• User Permissions - Manage roles

---

Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the ask query parameter:

GET /dev/product/security/authentication-authorization.md?ask=<question>

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.