Authentication & Authorization
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and Authorization (AuthN/AuthZ) within the Tuturuuu platform provide a secure foundation for managing user identities, workspace access, and API interactions. The system is designed to handle multi-session support, granular workspace permissions, and secure SDK integrations using a combination of Supabase Auth, JWT tokens, and API keys.
The architecture ensures that sensitive operations—such as AI chat interactions, document management, and storage access—are strictly gated by identity verification and permission checks. This prevents unauthorized access while allowing seamless collaboration across various platform applications like web, calendar, and tasks.
Sources: README.md, apps/web/src/data/legal/acceptable-use-sections.tsx:84-106
User Authentication
The platform utilizes Supabase Auth for core identity management. Users are required to maintain account integrity by securing credentials and using multi-factor authentication where available. Authentication state is primarily managed through Supabase clients that support Server-Side Rendering (SSR).
Core Components
- Supabase Client: Utilized both in standard (
createClient) and administrative (createAdminClient) modes to verify user sessions. - Session Verification: Routes check for the existence of a user via
supabase.auth.getUser()before processing requests. - Admin Bypass:
createAdminClientis used for system-level operations that bypass standard Row Level Security (RLS) triggers, though it still requires valid user context for most business logic.
Sources: packages/ai/src/chat/google/route.ts:184-197, apps/web/src/data/legal/acceptable-use-sections.tsx:96-106
Authentication Flow for AI Routes
When a request is made to an AI chat endpoint, the following sequence occurs to verify identity:
Workspace Authorization & Permissions
Authorization is governed by workspace membership and specific permission flags. Access control is enforced at the database level using Row Level Security (RLS) and at the application level through explicit checks.
Permission Types
Permissions are categorized by the module they control. Common permissions include:
| Permission | Description |
|---|---|
manage_drive | Required for storage operations (upload, download, list). |
manage_documents | Required for creating and searching documents. |
admin | Full access to workspace settings and user management. |
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:243-255, apps/web/src/data/legal/acceptable-use-sections.tsx:103-106
AI Credit and Budget Authorization
For AI-specific features, authorization includes a pre-flight "credit check" to ensure the workspace has sufficient balance for the requested model and task.
API Key and SDK Security
The platform supports programmatic access via API keys (ttr_...). To maintain security, the architecture emphasizes a "Security-First" proxy design.
SDK Integration Pattern
Developers are instructed to never expose API keys to the client browser. Instead, requests should be proxied through a server-side environment.
| Component | Responsibility |
|---|---|
| Client (Browser) | Makes requests to local, protected API routes. |
| Server (Next.js) | Holds the TUTURUUU_API_KEY and uses the SDK. |
| Tuturuuu Platform | Receives authenticated requests from the server. |
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:162-176
API Error Handling
The SDK provides specific error classes to help developers distinguish between different failure scenarios during authorization:
AuthenticationError: Triggered by an invalid or missing API key.AuthorizationError: Triggered when the key is valid but lacks the necessary permissions for the resource.RateLimitError: Triggered when the request frequency exceeds the workspace's allowed limit.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:103-134
Backend & WebSocket Security
The Rust-based backend provides its own authentication implementation for educational and specialized service purposes, utilizing JWT (JSON Web Tokens).
Authentication Endpoints
The backend exposes specific endpoints for managing production-level authentication:
POST /api/auth/register: User registration.POST /api/auth/login: Issuesaccess_tokenandrefresh_token.GET /api/auth/me: Requires aBearertoken in the Authorization header.
WebSocket Authorization
WebSocket connections can be established for echo, broadcast, or room-based communication. While some endpoints like /ws are for testing, others require identification to track active connections and room membership.
Sources: apps/backend/README.md:144-180, apps/backend/README.md:320-335
Conclusion
Authentication and Authorization in the Tuturuuu platform form a multi-layered security model. By combining Supabase's identity management with granular workspace permissions and a strict server-side proxy pattern for API keys, the platform ensures that user data and AI resources are accessible only to authorized entities. This structure supports both interactive web usage and secure automated integrations via the official SDK.
Sources: README.md, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:162-176