py_backend/ADMIN_SETUP.md

Admin Authentication Setup

This document explains how to set up admin authentication for the PromptAid Vision application.

Environment Variables

Add these environment variables to your .env file or Hugging Face Space secrets:

Required Variables

# Admin password for authentication
ADMIN_PASSWORD=your-secure-admin-password-here

# JWT secret key for token signing (use a strong, random key)
JWT_SECRET_KEY=your-secure-jwt-secret-key-here

Optional Variables

# Database connection
DATABASE_URL=postgresql://username:password@localhost:5432/database_name

# Storage configuration
STORAGE_PROVIDER=local
STORAGE_DIR=./uploads

How It Works

1. Admin Login

• Users click "Admin Login" in the header navigation
• They enter the admin password
• If correct, they receive a JWT token valid for 24 hours

2. Authentication Flow

• Frontend stores the JWT token in localStorage
• Token is sent with each admin API request in Authorization header
• Backend verifies token validity and role

3. Security Features

• JWT tokens expire after 24 hours
• Tokens are verified on each admin request
• Password is stored in environment variables (not in code)

API Endpoints

POST /api/admin/login

• Purpose: Authenticate admin user
• Body: {"password": "admin_password"}
• Response: {"token": "jwt_token", "expires_at": "timestamp"}

POST /api/admin/verify

• Purpose: Verify admin token
• Headers: Authorization: Bearer <token>
• Response: {"valid": true/false, "message": "..."}

GET /api/admin/status

• Purpose: Get admin status (protected endpoint)
• Headers: Authorization: Bearer <token>
• Response: {"status": "authenticated", "role": "admin", "timestamp": "..."}

Development vs Production

Development

• Default password: admin123
• Default JWT secret: your-secret-key-change-in-production
• ⚠️ Change these in production!

Production

• Use strong, random passwords
• Use secure JWT secret keys
• Store secrets in environment variables or Hugging Face Space secrets
• Consider implementing password hashing for additional security

Future Enhancements

• User-specific accounts and permissions
• Role-based access control
• Password hashing with bcrypt
• Session management
• Audit logging
• Two-factor authentication

Troubleshooting

Common Issues

1. "Invalid admin password"

   • Check that ADMIN_PASSWORD environment variable is set correctly
   • Ensure no extra spaces or characters

2. "Token is invalid or expired"

   • Token may have expired (24-hour limit)
   • Try logging in again
   • Check JWT_SECRET_KEY is consistent

3. "Method Not Allowed"

   • Ensure admin router is properly included in main.py
   • Check API endpoint URLs are correct

Debug Steps

1. Verify environment variables are loaded
2. Check backend logs for authentication errors
3. Verify JWT token format in browser localStorage
4. Test API endpoints directly with tools like curl or Postman