> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Secure authentication with Clerk and Convex integration
## Overview
The Twigz API uses **Clerk** for authentication integrated with **Convex** for secure, scalable user management. This system supports multiple authentication methods and provides role-based access control for customers, store owners, and administrators.
## Authentication Flow
Users authenticate through Clerk using email, phone, or social providers
Clerk generates a secure JWT token for the authenticated user
Token is automatically validated by Convex for API access
API functions check user roles and permissions automatically
## Setup Authentication
### Frontend Setup (React)
```typescript Next.js App Router theme={null}
// app/layout.tsx
import { ClerkProvider } from '@clerk/nextjs'
import { ConvexProviderWithClerk } from "convex/react-clerk";
import { ConvexReactClient } from "convex/react";
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
{children}
)
}
```
```typescript React Component theme={null}
// components/AuthenticatedApp.tsx
import { SignIn, SignUp, UserButton, useUser } from "@clerk/nextjs";
import { Authenticated, Unauthenticated } from "convex/react";
function AuthenticatedApp() {
return (
<>
Welcome to Twigz
{/* Navigation */}
{/* Main App Content */}
);
}
export default AuthenticatedApp;
```
```typescript React Native theme={null}
// App.tsx
import { ClerkProvider, SignedIn, SignedOut } from '@clerk/clerk-expo';
import { ConvexProviderWithClerk } from 'convex/react-clerk';
import { ConvexReactClient } from 'convex/react';
const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!);
export default function App() {
return (
);
}
```
### Backend Setup (Convex)
```typescript Convex Configuration theme={null}
// convex/auth.config.ts
export default {
providers: [
{
domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
applicationID: "convex",
},
]
};
```
```typescript Environment Variables theme={null}
// .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
CLERK_JWT_ISSUER_DOMAIN=https://your-clerk-domain.clerk.accounts.dev
```
## User Roles & Permissions
The system supports three main user roles:
**Permissions**: Place orders, manage cart, view own data\
**Access**: Customer functions, public store data
**Permissions**: Manage store, products, orders, settings\
**Access**: Store functions, own store data, customer orders
**Permissions**: Platform management, store approval, analytics\
**Access**: All functions, system-wide data
## Protected API Calls
```typescript Authenticated Queries theme={null}
import { useQuery, useMutation } from "convex/react";
import { api } from "./convex/_generated/api";
function CustomerProfile() {
// Automatically authenticated - returns data for current user
const profile = useQuery(api.customers.account.getCustomerProfile);
if (profile === undefined) return
Loading...
;
if (profile === null) return
Please complete your profile
;
return
Welcome, {profile.name}!
;
}
function StoreOwnerDashboard() {
// Only accessible to store owners
const store = useQuery(api.stores.queries.getStoreByAuthenticatedOwner);
const updateStore = useMutation(api.stores.operations.updateStore);
const handleStoreUpdate = async (updates: any) => {
try {
await updateStore(updates);
} catch (error) {
if (error.message.includes('permission')) {
console.error('Access denied: User is not a store owner');
}
}
};
return
{/* Store dashboard */}
;
}
```
```typescript Server-side Authentication theme={null}
// For server-side API calls
import { ConvexHttpClient } from "convex/node";
const convex = new ConvexHttpClient(process.env.CONVEX_URL!);
// Get user token from Clerk
const token = await getAuth(req).getToken({ template: "convex" });
// Make authenticated API call
const result = await convex.query(
"customers.account.getCustomerProfile",
{},
{ token }
);
```
## Authentication Patterns
### Role-based Component Access
```typescript Role Guard Component theme={null}
import { useUser } from "@clerk/nextjs";
interface RoleGuardProps {
allowedRoles: ('customer' | 'store_owner' | 'admin')[];
children: React.ReactNode;
fallback?: React.ReactNode;
}
function RoleGuard({ allowedRoles, children, fallback }: RoleGuardProps) {
const { user } = useUser();
const userRole = user?.publicMetadata?.role as string;
if (!userRole || !allowedRoles.includes(userRole as any)) {
return fallback ||
Access denied
;
}
return <>{children};
}
// Usage
```
```typescript Custom Hook theme={null}
function useUserRole() {
const { user } = useUser();
const role = user?.publicMetadata?.role as string;
return {
role,
isCustomer: role === 'customer',
isStoreOwner: role === 'store_owner',
isAdmin: role === 'admin',
hasAccess: (requiredRoles: string[]) => requiredRoles.includes(role)
};
}
// Usage in component
function MyComponent() {
const { isStoreOwner, isAdmin, hasAccess } = useUserRole();
return (