🧠 Face Recognition Authentication API

A lightweight Flask-based REST API that enables face registration and login using facial recognition. Built with face_recognition, Pillow, and NumPy — no database required.

---

📸 Features

• Register a user by name and face image
• Login by matching a live face against stored encodings
• Encodings persisted locally via pickle (no DB setup needed)
• Registered face images saved to disk for reference
• Simple REST API — easy to integrate with any frontend

---

🛠️ Tech Stack

Library	Purpose
Flask	Web framework / REST API
face_recognition	Face detection & encoding (built on dlib)
Pillow	Image parsing
NumPy	Image array conversion
pickle	Persistent storage of face encodings

---

⚙️ Prerequisites

face_recognition depends on dlib, which requires CMake and a C++ compiler.

Install system dependencies (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y cmake build-essential libopenblas-dev liblapack-dev

Install system dependencies (macOS)

brew install cmake

---

🚀 Installation

# 1. Clone the repository
git clone https://github.com/your-username/face-recognition-api.git
cd face-recognition-api

# 2. Create and activate a virtual environment (recommended)
python -m venv venv
source venv/bin/activate       # On Windows: venv\Scripts\activate

# 3. Install Python dependencies
pip install flask face_recognition pillow numpy

---

▶️ Running the Server

python app.py

The API will start at http://127.0.0.1:5000 by default.

---

📡 API Endpoints

POST /register

Registers a new user with their name and face image.

Request Body (JSON):

{
  "name": "John Doe",
  "image": "data:image/jpeg;base64,<base64-encoded-image>"
}

Responses:

Status	Body
200	{ "message": "John Doe registered" }
400	{ "error": "Name and image are required" }
400	{ "error": "No face found" }
400	{ "error": "Invalid image" }

---

POST /login

Attempts to identify the person in the provided image.

Request Body (JSON):

{
  "image": "data:image/jpeg;base64,<base64-encoded-image>"
}

Responses:

Status	Body
200	{ "message": "Welcome, John Doe!" }
401	{ "error": "Face not recognized" }
400	{ "error": "No face found" }
400	{ "error": "Invalid image" }

---

📁 Project Structure

face-recognition-api/
├── app.py               # Main Flask application
├── encodings.pkl        # Auto-generated: stored face encodings
├── faces/               # Auto-generated: saved face images per user
│   └── John Doe.jpg
└── README.md

---

🧪 Example Usage (Python)

import requests
import base64

# Load and encode image
with open("face.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")
image_data = f"data:image/jpeg;base64,{encoded}"

# Register
requests.post("http://127.0.0.1:5000/register", json={
    "name": "John Doe",
    "image": image_data
})

# Login
response = requests.post("http://127.0.0.1:5000/login", json={
    "image": image_data
})
print(response.json())

---

⚠️ Limitations & Notes

• One face per registration: Only the first detected face in the image is stored.
• Tolerance: Login uses a default tolerance of 0.6. Lower values are stricter.
• No authentication layer: This API has no token/session management — add one before deploying to production.
• Storage: Encodings are stored in a local .pkl file. For multi-user or production use, consider a proper database.
• Performance: dlib-based face recognition is CPU-intensive. A GPU build of dlib will significantly speed things up.

---

🔒 Security Considerations

• Do not expose this API publicly without adding authentication (e.g., JWT, API keys).
• Images are stored in plaintext in the faces/ directory — consider encrypting at rest for sensitive deployments.
• Face recognition is not foolproof — liveness detection is not included.

---

📄 License

MIT License. See LICENSE for details.