Access Control

Teela enforces access control at multiple levels: role-based permissions determine what actions a user can perform, connection-level authorization determines what data a user can reach, and authentication controls verify identity through passwords, multi-factor authentication, and API tokens.

Access Control Principles

All access decisions in Teela are governed by three principles:

• Least privilege. Users and services are granted the minimum permissions required for their role. No user has broader access than their function demands.
• Need-to-know. Data access is scoped not only by role but by explicit connection assignment. A user with the "User" role sees only the database connections their administrator has granted.
• Separation of duties. Administrative functions (user management, security settings, training configuration) are separated from operational functions (querying, dashboards). No single role combines unrestricted data access with unrestricted administrative control.

Role-Based Access Control (RBAC)

Teela implements three roles with hierarchical permissions. Each user is assigned exactly one role within their organization.

Permission Matrix

Capability	Owner	Client Admin	User
User Management
Create / edit / deactivate users	Yes	Yes	No
Assign roles	Yes	Yes	No
Enforce MFA policy	Yes	Yes	No
Configure password policy	Yes	Yes	No
Connection Management
Create / edit connections	Yes	Yes	Personal only
Assign connections to users	Yes	Yes	No
View connection credentials	No (masked)	No (masked)	No
Training & Configuration
Manage training data (DDL, SQL, docs)	Yes	Yes	No
Configure aliases and metadata	Yes	Yes	No
Data Access
Run queries	Yes	Yes	Yes
Create / manage DataClips	Yes	Yes	Yes
Create / manage dashboards	Yes	Yes	Yes
Billing & Subscription
Manage billing and subscription	Yes	No	No
Security & Audit
View audit logs	Yes	Yes	No
Manage security settings	Yes	Yes	No

Role Descriptions

Owner has all the same permissions as a Client Admin, plus access to billing and subscription management. This is typically the person who created the Teela account for the organization.

Client Admin is the administrative role within an organization. Client Admins manage users, connections, training data, aliases, and security settings for their organization.

User is the standard operational role. Users can run natural-language queries, create DataClips and dashboards, and manage personal connections. They cannot manage other users, modify training data, or access security settings.

Authentication

Token-Based API Authentication

Teela uses token-based authentication for API access:

• API tokens are generated per user and hashed with bcrypt (cost factor 12+) before storage.
• A SHA-256 lookup hash enables fast token retrieval without exposing the token value.
• Tokens expire after 30 days by default. A 7-day grace period allows auto-refresh of expiring tokens to maintain session continuity.
• Expired tokens cannot be refreshed and require re-authentication.

Session Management

• Sessions are governed by token expiration (30 days). There is no separate inactivity timeout.
• Active sessions are invalidated on password change or account deactivation.
• Session tokens are transmitted only over HTTPS and are not accessible to client-side JavaScript.

CSRF Protection

Teela implements CSRF protection using a dual-verification approach:

• A CSRF token is stored in a secure, HttpOnly cookie.
• The frontend includes a custom X-Requested-With: XMLHttpRequest header on every request.
• The backend validates both the cookie and the header before processing state-changing requests.

Rate Limiting

All authentication routes are rate-limited to mitigate brute-force and credential-stuffing attacks. Rate limits apply to login attempts, token refresh, password reset, and MFA verification endpoints.

Multi-Factor Authentication (MFA)

Teela supports multi-factor authentication through Passkeys using the WebAuthn/FIDO2 standard. Passkeys provide phishing-resistant, cryptographic authentication that is stronger than traditional TOTP or SMS-based MFA.

MFA Configuration

Setting	Value
MFA method	Passkeys (WebAuthn/FIDO2)
Enforcement	Optional or admin-enforced per organization
Enrollment grace period	7 days after enforcement is enabled
Recovery method	Email-based recovery
Recovery rate limit	3 requests per hour
Multiple devices	Supported

MFA Lifecycle

1. Enrollment. When a Client Admin enables MFA enforcement, users in that organization have a 7-day grace period to register a Passkey device. During the grace period, users can authenticate without MFA but receive enrollment prompts.
2. Authentication. After enrollment, users must present their Passkey on each login.
3. Device management. Users can register multiple Passkey devices to ensure access continuity. Device registration and removal are logged.
4. Recovery. If a user loses access to all registered devices, they can request an email-based recovery. Recovery requests are rate-limited to 3 per hour to prevent abuse.

MFA Audit Events

All MFA-related events are logged for audit purposes:

• Passkey enrollment and removal
• MFA authentication success and failure
• Recovery requests and completions
• Admin enforcement changes

Password Policies

Teela enforces configurable password policies to protect against weak and compromised credentials.

Password Requirements

Policy	Setting
Minimum length	12 characters
Complexity	At least 3 of 4 character types (uppercase, lowercase, digits, special characters)
Dictionary check	Common words and patterns are rejected
History	Cannot reuse any of the last 12 passwords
Expiration	Configurable: 30 to 365 days (default: 90 days)
Expiration warning	7 days before expiration

Account Lockout

Policy	Setting
Failed attempts before lockout	5
Lockout duration	15 minutes
Lockout scope	Per account

Failed login attempts are tracked per account. After 5 consecutive failures, the account is locked for 15 minutes. The lockout counter resets on successful authentication.

Access Provisioning and Deprovisioning

Provisioning

1. A Client Admin creates the user account and assigns a role.
2. The Client Admin assigns specific database connections to the user.
3. If MFA is enforced, the user has 7 days to register a Passkey device.
4. The user sets their password and gains access according to their role and connection assignments.

Deprovisioning

1. The Client Admin deactivates the user account.
2. All active sessions are immediately invalidated.
3. API tokens associated with the account are revoked.
4. Connection assignments are removed.
5. The deactivation is logged in the audit trail.

Deprovisioning is immediate. There is no grace period during which a deactivated user can access the system.

Quarterly Access Reviews

Teela conducts quarterly access reviews to ensure that permissions remain appropriate:

• All user-role assignments are reviewed against current job functions.
• Connection assignments are validated with data owners.
• Inactive accounts are identified and deactivated.
• Privileged roles (Client Admin) receive additional scrutiny.
• Review results are documented and retained for compliance purposes.

Audit Logging

Teela maintains audit logs for all security-relevant events, including:

• Authentication events (login, logout, failed attempts, lockouts)
• MFA events (enrollment, removal, recovery, enforcement changes)
• Password changes and resets
• User provisioning and deprovisioning
• Role and connection assignment changes
• Administrative setting changes

Logs are centralized via Sentry and retained according to the organization's data retention policy. For details on data retention and classification, see Data Protection. For details on how credentials and tokens are protected cryptographically, see Encryption.