React authentication hooks, components and server middleware for Exyconn Auth integration
npm install @exyconn/authbash
npm install @exyconn/auth
or
yarn add @exyconn/auth
or
pnpm add @exyconn/auth
`
Subpackages
This package provides two subpackages for different use cases:
| Subpackage | Import | Use Case |
|------------|--------|----------|
| @exyconn/auth | Main entry | All client-side features |
| @exyconn/auth/client | Client-only | React hooks & components |
| @exyconn/auth/server | Server-only | Express middleware |
---
Client Usage (
@exyconn/auth or @exyconn/auth/client)
$3
`tsx
import { ExyconnAuthProvider } from '@exyconn/auth';
function App() {
return (
apiAuthBaseUrl="https://exyconn-auth-server.exyconn.com"
uiAuthUrl="https://auth.exyconn.com"
apiKey="exy_your_api_key"
>
);
}
`
$3
`tsx
import { useIsAuthenticated, useUser, useLogout } from '@exyconn/auth';
function ProfilePage() {
const isAuthenticated = useIsAuthenticated();
const user = useUser();
const logout = useLogout();
if (!isAuthenticated) {
return ;
}
return (
Hello, {user?.firstName}!
Email: {user?.email}
);
}
`
$3
`tsx
import { RequireAuth, RequireRole, RequirePermission } from '@exyconn/auth';
// Require authentication
}>
// Require specific role
}>
// Require specific permission
}>
`
$3
`tsx
import { ProtectedRoute } from '@exyconn/auth';
// Automatically redirects to login if not authenticated
// With custom loading
}>
// With custom fallback (no redirect)
} redirectToLogin={false}>
`
---
Server Usage (
@exyconn/auth/server)
$3
`typescript
import express from 'express';
import { authMiddleware } from '@exyconn/auth/server';
const app = express();
// Set environment variables
// API_KEY=your_api_key
// AUTH_API_BASE_URL=https://exyconn-auth-server.exyconn.com
// Protected route
app.get('/api/protected', authMiddleware, (req, res) => {
res.json({
message: Hello ${req.user?.firstName}!,
user: req.user,
});
});
`
$3
`typescript
import { createAuthMiddleware } from '@exyconn/auth/server';
const authMiddleware = createAuthMiddleware({
apiKey: 'your-api-key',
apiAuthBaseUrl: 'https://your-auth-server.com',
onError: (error, req, res) => {
res.status(401).json({
success: false,
error
});
},
});
app.get('/api/protected', authMiddleware, (req, res) => {
res.json({ user: req.user });
});
`
$3
`typescript
import { validateToken } from '@exyconn/auth/server';
const result = await validateToken({
token: 'user-token-here',
apiKey: 'your-api-key',
});
if (result.valid) {
console.log('User:', result.user);
} else {
console.error('Invalid:', result.error);
}
`
---
Provider Configuration
`tsx
// Base URL for your Exyconn Auth API server (required)
apiAuthBaseUrl="https://exyconn-auth-server.exyconn.com"
// Base URL for the Auth UI (required)
uiAuthUrl="https://auth.exyconn.com"
// API key for multi-tenant authentication (required)
apiKey="exy_your_api_key"
// Whether to auto-fetch user on mount (default: true)
autoFetch={true}
// Callback when authentication fails
onAuthError={(error) => console.error(error)}
// Callback when user is successfully authenticated
onAuthSuccess={(user) => console.log('Logged in:', user)}
// Custom headers for API requests
headers={{ 'X-Custom-Header': 'value' }}
>
{children}
`
---
Available Hooks
| Hook | Return Type | Description |
|------|-------------|-------------|
| useExyconnAuth() | ExyconnAuthContextValue | Full auth context |
| useIsAuthenticated() | boolean | Check if authenticated |
| useUser() | AuthUser \| null | Get current user |
| useOrganization() | AuthOrganization \| null | Get organization |
| useRole() | AuthRole \| null | Get user role |
| useRoleSlug() | string \| null | Get role slug |
| useHasRole(role) | boolean | Check specific role |
| useHasPermission(perm) | boolean | Check permission |
| useHasAnyPermission(perms) | boolean | Check any permission |
| useHasAllPermissions(perms) | boolean | Check all permissions |
| useAuthLoading() | boolean | Loading state |
| useAuthError() | string \| null | Error state |
| useLogout() | () => void | Logout function |
| useAuthToken() | { get, set } | Token management |
| useApiKey() | { get, set } | API key management |
| useAuthUrls() | { getLoginUrl, ... } | Auth URL builders |
---
Guard Components
| Component | Props | Description |
|-----------|-------|-------------|
| | fallback, loading | Require authentication |
| | role, fallback, loading | Require specific role |
| | permission, fallback, loading | Require permission |
| | permissions[], fallback, loading | Require any permission |
| | permissions[], fallback, loading | Require all permissions |
| | fallback, loading, redirectToLogin, redirectUrl | Route protection |
---
Types
$3
`typescript
interface AuthUser {
id: string;
firstName: string;
lastName: string;
email: string;
profilePicture?: string;
role: string;
isVerified?: boolean;
mfaEnabled?: boolean;
createdAt: string;
lastLoginAt?: string;
}
`
$3
`typescript
interface AuthUser {
id: string;
email: string;
firstName?: string;
lastName?: string;
profilePicture?: string;
role?: string;
isVerified?: boolean;
}
`
---
API Endpoints
This package uses the following Exyconn Auth API endpoints:
- GET /v1/api/auth/me - Get current user
- GET /v1/api/auth/role - Get current user's role
- POST /v1/api/auth/logout - Logout user
- POST /token/validate - Validate token (server-side)
---
Example: Full Stack Setup
$3
`tsx
import { ExyconnAuthProvider, ProtectedRoute, useUser } from '@exyconn/auth';
function App() {
return (
apiAuthBaseUrl="https://exyconn-auth-server.exyconn.com"
uiAuthUrl="https://auth.exyconn.com"
apiKey="exy_your_api_key"
>
);
}
function Dashboard() {
const user = useUser();
return (
Welcome, {user?.firstName}!
);
}
`
$3
`typescript
import express from 'express';
import cors from 'cors';
import { createAuthMiddleware } from '@exyconn/auth/server';
const app = express();
app.use(cors({ origin: 'http://localhost:3000', credentials: true }));
app.use(express.json());
const authMiddleware = createAuthMiddleware({
apiKey: process.env.API_KEY!,
});
app.get('/api/user', authMiddleware, (req, res) => {
res.json({ user: req.user });
});
app.listen(4000);
``