Skip to main content
Get your Soft-Bee API up and running in just a few minutes. This guide will walk you through setup, configuration, and making your first API call.

​
Prerequisites

Before you begin, ensure you have the following installed:

Python 3.10+

Required for running the Flask application

PostgreSQL

Database for storing beekeeping data

​
Quick Setup

1

Clone the Repository

Get the source code from your repository:
git clone <your-repository-url>
cd Soft-Bee-Back-End
2

Run the Initialization Script

Use the provided initialization script to set up your environment:
chmod +x init_project.sh
./init_project.sh
This script will:
  • Create a Python virtual environment
  • Install all base dependencies
  • Optionally install development dependencies
  • Set up the project structure
When prompted, type s or y to install development dependencies for a better development experience.
3

Configure Environment Variables

Copy the example environment file and configure your settings:
cp .env.example .env
Update the .env file with your configuration:
.env
# Environment
FLASK_ENV=local

# Security Keys
SECRET_KEY=your-secret-key-here
JWT_KEY=your-jwt-secret-key-here

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/softbee_local

# Email (Optional for testing)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-email-password
Change the SECRET_KEY and JWT_KEY values before deploying to production!
4

Initialize the Database

Create the database and run migrations:
# Activate virtual environment (if not already active)
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Initialize migrations
flask db init
flask db migrate -m "Initial migration"
flask db upgrade
Make sure PostgreSQL is running and the database specified in DATABASE_URL exists.
5

Start the Development Server

Run the Flask application:
flask run
# Or use python directly
python index.py
You should see output like:
🚀 Iniciando aplicación en entorno: local
⚙️  Configuración activa: LocalConfig
📂 Usando base de datos: PostgreSQL
🌐 URLs configuradas:
   Frontend: http://localhost:3000
   Backend: http://localhost:5000
🐛 Debug mode: True
 * Running on http://127.0.0.1:5000

​
Make Your First API Call

Now that your server is running, let’s test it with a real API call.

​
Register a New User

Create a new user account using the registration endpoint: 
curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "beekeeper@example.com",
    "username": "beekeeper123",
    "password": "SecurePass123!",
    "confirm_password": "SecurePass123!"
  }'
Expected Response (201 Created): 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "beekeeper@example.com",
  "username": "beekeeper123",
  "is_verified": false,
  "created_at": "2026-03-06T10:30:00",
  "message": "User registered successfully"
}
Password must contain at least 8 characters with:
  • One uppercase letter
  • One lowercase letter
  • One number
  • One special character

​
Login to Get Access Token

Authenticate and receive JWT tokens: 
curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "beekeeper@example.com",
    "password": "SecurePass123!",
    "remember_me": false
  }'
Expected Response (200 OK): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1440,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "beekeeper@example.com",
    "username": "beekeeper123",
    "is_active": true,
    "is_verified": false,
    "created_at": "2026-03-06T10:30:00",
    "updated_at": "2026-03-06T10:30:00"
  }
}

​
Verify API Health

Check that the authentication feature is running correctly: 
curl http://localhost:5000/api/v1/auth/health
Response: 
{
  "status": "healthy",
  "feature": "auth",
  "version": "1.0.0",
  "endpoints": [
    "/api/v1/auth/login",
    "/api/v1/auth/register",
    "/api/v1/auth/logout",
    "/api/v1/auth/verify"
  ]
}

​
Next Steps

API Reference

Explore all available endpoints and their parameters

Architecture

Learn about the Clean Architecture and DDD patterns used

Authentication

Deep dive into JWT authentication and security

Error Handling

Understand error codes and how to handle them

​
Troubleshooting

Make sure PostgreSQL is running and the DATABASE_URL in your .env file is correct.Test your database connection:
psql -U postgres -h localhost -d softbee_local
If you’re having trouble with the virtual environment:Linux/Mac:
python3 -m venv venv
source venv/bin/activate
Windows:
python -m venv venv
venv\Scripts\activate
If you encounter migration errors, try:
# Remove existing migrations
rm -rf migrations/

# Reinitialize
flask db init
flask db migrate -m "Initial migration"
flask db upgrade
If port 5000 is already in use, specify a different port:
flask run --port 5001
Or update FLASK_RUN_PORT in your .flaskenv file.

Build docs developers (and LLMs) love

Get started for freeTalk to us