Authentication & Privy Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup Admin dashboard utilizes Privy as its core authentication and identity management provider. The integration is designed to secure administrative routes, manage user sessions, and provide detailed analytics on user sign-ins across the platform. Authentication is handled on the client side using the @privy-io/react-auth SDK, with backend verification performed via Bearer tokens passed to protected API endpoints.
Sources: package.json:16, providers/PrivyProvider.tsx:1-38, hooks/useIsAdmin.ts:1-32
Architecture and Provider Setup
The application is wrapped in a PrivyProvider which initializes the authentication context using a specific Application ID. This provider configures the visual appearance of the login interface and restricts login methods primarily to email.
Privy Configuration
The provider is initialized with the following parameters:
- App ID: Sourced from the
NEXT_PUBLIC_PRIVY_APP_IDenvironment variable. - Login Methods: Restricted to
['email']. - Embedded Wallets: Configured to create wallets for "users-without-wallets" upon login.
- Theming: Uses a light theme with a specific accent color (
#003199) and the Recoup wordmark logo.
Sources: providers/PrivyProvider.tsx:14-36
Authentication State Flow
The application manages access levels by first checking the general authentication status through Privy and subsequently verifying administrative privileges through an internal check.
The logic for this flow is primarily implemented in the HomeContent component, which coordinates between the usePrivy hook and the custom useIsAdmin hook.
Sources: components/Home/HomeContent.tsx:7-41
Admin Authorization
Simply being authenticated via Privy is insufficient for accessing the dashboard. The system implements a secondary authorization layer to verify the user's admin status.
useIsAdmin Hook
The useIsAdmin hook validates the user's identity by sending the Privy access token to the backend.
- Endpoint:
${API_BASE_URL}/api/admins - Method: GET
- Header:
Authorization: Bearer <token> - Logic: If the response is not
okor theisAdminfield in the JSON response is false, the hook returnsfalse.
Sources: hooks/useIsAdmin.ts:11-32
Integration with External APIs
The dashboard fetches various metrics by acting as an authenticated client. Every request to a protected /api/admins/* route includes a Bearer token retrieved from Privy's getAccessToken() method.
Request Pattern
All administrative data hooks follow a consistent pattern:
- Ensure Privy is
readyand the user isauthenticated. - Retrieve the JWT access token.
- Pass the token to a library function that executes the
fetchrequest.
Data Models and Types
The integration defines specific types to handle the raw data returned from Privy's Management API, which utilizes snake_case naming conventions.
| Type | Description | Key Fields |
|---|---|---|
PrivyUser | Representation of a user in the Privy system. | id, created_at, linked_accounts, is_guest |
PrivyLinkedAccount | Details about connected auth methods. | type, address, verified_at |
PrivyLoginsResponse | Standard API response for login stats. | status, total, total_new, total_active, logins |
Sources: types/privy.ts:1-26
Summary of Configuration
The following table summarizes the environment and dependency requirements for the Authentication system:
| Requirement | Value / Source |
|---|---|
| SDK | @privy-io/react-auth v1.88.4 |
| Env Var | NEXT_PUBLIC_PRIVY_APP_ID |
| Auth Type | Bearer Token (JWT) |
| Login Type | Email-based |
| Admin Route | /api/admins |
Sources: package.json:16, providers/PrivyProvider.tsx:14-20, hooks/useIsAdmin.ts:21-23
The Authentication and Privy integration ensures that only authorized Recoup staff can access sensitive platform data, while providing the infrastructure to monitor user engagement and sign-in patterns through the Admin dashboard.