# Authentication Setup

This guide covers user authentication configuration for the web dashboard and API access.

## Overview

SMS Campaign Manager supports two authentication methods:

- **Session-based**: Username/password login for web dashboard
- **API key-based**: Header authentication for scripts and automation

Both methods work simultaneously.

## Web Dashboard Authentication

### Configure Admin User

Add these lines to your `.env` file:

```env
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!
```

Restart the application:

```bash
docker compose restart
```

The admin user is created automatically on startup.

### Login Process

1. Open `http://localhost:5000/`
2. You'll be redirected to `/login`
3. Enter your credentials
4. After login, sessions last 24 hours

### Session Features

- 24-hour session duration
- HTTP-only cookies for security
- Automatic session cleanup
- Login tracking and auditing

## API Key Authentication

API keys are used for programmatic access and automation scripts.

### Key Types

| Key | Variable | Purpose |
|-----|----------|---------|
| Admin | `ADMIN_API_KEY` | Full access including database reset |
| User | `USER_API_KEY` | Standard operations |
| Termux | `TERMUX_API_KEY` | Android device communication |

### Usage

Include the key in request headers:

```bash
# X-API-Key header
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/endpoint

# Bearer token
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:5000/api/endpoint
```

## User Roles

### Admin Role

Full system access:

- All user permissions
- Create and delete users
- Database reset
- System configuration

### User Role

Standard operations:

- Create and manage campaigns
- Send SMS messages
- Upload CSV files
- View analytics
- Change own password

## Managing Users

Use the CLI tool to manage users:

```bash
python3 manage_users.py
```

Available options:

1. Create new user
2. List all users
3. Delete user
4. Change password

### Create User via CLI

```bash
python3 manage_users.py
# Select option 1
# Enter username, password, role
```

### Create User via API (Admin Only)

```bash
curl -X POST http://localhost:5000/api/admin/users/create \
  -H "Cookie: session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","password":"SecurePass123!","role":"user"}'
```

## Testing Authentication

### Test Web Login

```bash
# Should redirect to login
curl -i http://localhost:5000/

# Login via API
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword"}'
```

### Test API Authentication

```bash
# Should fail (no key)
curl http://localhost:5000/api/campaign/list

# Should succeed
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list
```

## Security Features

- PBKDF2 password hashing (100,000 iterations)
- HTTP-only session cookies
- Secure session tokens
- Constant-time password comparison
- Failed login tracking

## Troubleshooting

### Can't Log In

```bash
# Verify user exists
python3 manage_users.py
# Select option 2

# Reset password via .env
nano .env
# Update ADMIN_PASSWORD
docker compose restart
```

### Session Expires Too Quickly

Session duration is configured in `src/app.py`. Default is 24 hours.

### Forgot Password

```bash
# Via CLI
python3 manage_users.py
# Select option 4 (Change password)

# Or reset via .env
nano .env
# Update ADMIN_PASSWORD
docker compose restart
```

## Related Documentation

- [Installation Guide](installation.md) - Initial setup
- [Security Setup](../security/security-setup.md) - API key configuration
- [User Management](../guides/user-management.md) - Detailed user guide
- [API Endpoints](../api/endpoints.md) - Authentication endpoints