userauthenticationandauthorizationservice-692iqk/README.md

# User Authentication and Authorization Service

A FastAPI service providing user authentication and authorization features including:

- User registration and management
- JWT authentication
- Password reset functionality
- Role-based access control

## Features

- **User Management:**
  - User registration
  - User profile management
  - Email verification (implementation ready)

- **Authentication:**
  - JWT-based authentication with access and refresh tokens
  - Secure password hashing with bcrypt
  - Password reset functionality

- **Authorization:**
  - Role-based access control
  - Admin functionality for user management
  - Fine-grained permission control

## Installation

1. Clone the repository
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Set up environment variables (or create a `.env` file)
4. Run database migrations:
   ```bash
   alembic upgrade head
   ```
5. Start the server:
   ```bash
   uvicorn main:app --reload
   ```

## API Documentation

### Authentication Endpoints

#### Register a new user
```
POST /auth/signup
```
Request body:
```json
{
  "email": "user@example.com",
  "password": "StrongPassword123",
  "first_name": "John",
  "last_name": "Doe"
}
```
Response:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

> Note: The signup endpoint returns authentication tokens directly, allowing immediate user access without a separate login step.

#### Login
```
POST /auth/login
```
Request body:
```json
{
  "email": "user@example.com",
  "password": "StrongPassword123"
}
```
Response:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

#### Refresh token
```
POST /auth/refresh-token
```
Request body:
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Request password reset
```
POST /auth/password-reset
```
Request body:
```json
{
  "email": "user@example.com"
}
```

#### Reset password
```
POST /auth/password-reset/confirm
```
Request body:
```json
{
  "token": "reset_token_here",
  "password": "NewStrongPassword123",
  "password_confirm": "NewStrongPassword123"
}
```

#### Change password
```
POST /auth/password-change
```
Request body:
```json
{
  "current_password": "StrongPassword123",
  "new_password": "NewStrongPassword123"
}
```

### User Management Endpoints

#### Get current user
```
GET /users/me
```

#### Update current user
```
PUT /users/me
```
Request body:
```json
{
  "first_name": "John",
  "last_name": "Smith"
}
```

#### Get all users (admin only)
```
GET /users
```

#### Get user by ID (admin only)
```
GET /users/{user_id}
```

#### Update user (admin only)
```
PUT /users/{user_id}
```

#### Delete user (admin only)
```
DELETE /users/{user_id}
```

#### Verify user (admin only)
```
POST /users/{user_id}/verify
```

### Role Management Endpoints

#### Get user roles (admin only)
```
GET /users/{user_id}/roles
```

#### Add role to user (admin only)
```
POST /users/{user_id}/roles/{role_id}
```

#### Remove role from user (admin only)
```
DELETE /users/{user_id}/roles/{role_id}
```

## Security Considerations

- Passwords are hashed using bcrypt
- JWT tokens with appropriate expiration times
- Role-based authorization for sensitive operations
- Input validation using Pydantic models

## Health Check

The service provides a health check endpoint:
```
GET /health
```

## Development

The project follows standard FastAPI practices and uses:
- SQLAlchemy ORM for database operations
- Alembic for database migrations
- Pydantic for data validation
- JWT for authentication tokens