docs/dev/auth/AUTH_API_GUIDE.md

# Authentication API Guide

Complete authentication system with user registration, login, and profile management.

**Powered by Supabase Auth** - Secure, managed authentication with JWT tokens.

## Endpoints

### 1. Register New User
```http
POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+254712345678"
}
```

**Response:**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "is_active": true,
    "is_verified": false
  }
}
```

### 2. Login
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123"
}
```

**Response:** Same as registration

### 3. Get Current User Profile
```http
GET /api/v1/auth/me
Authorization: Bearer <your_token>
```

**Response:**
```json
{
  "id": "uuid",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+254712345678",
  "is_active": true,
  "is_verified": false,
  "profile_picture_url": null,
  "bio": null,
  "created_at": "2025-11-15T19:00:00",
  "updated_at": "2025-11-15T19:00:00",
  "full_name": "John Doe"
}
```

### 4. Update Profile
```http
PUT /api/v1/auth/me
Authorization: Bearer <your_token>
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "+254798765432",
  "bio": "Software developer",
  "profile_picture_url": "https://example.com/photo.jpg"
}
```

**Response:** Updated user profile

### 5. Change Password
```http
POST /api/v1/auth/change-password
Authorization: Bearer <your_token>
Content-Type: application/json

{
  "current_password": "SecurePass123",
  "new_password": "NewSecurePass456"
}
```

**Response:**
```json
{
  "message": "Password changed successfully"
}
```

## Password Requirements

- Minimum 8 characters
- At least 1 digit
- At least 1 uppercase letter

## Testing with cURL

### Register
```bash
curl -X POST https://your-space.hf.space/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "TestPass123",
    "first_name": "Test",
    "last_name": "User"
  }'
```

### Login
```bash
curl -X POST https://your-space.hf.space/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "TestPass123"
  }'
```

### Get Profile (use token from login)
```bash
curl -X GET https://your-space.hf.space/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

## Error Responses

### 400 Bad Request
```json
{
  "detail": "Email already registered"
}
```

### 401 Unauthorized
```json
{
  "detail": "Incorrect email or password"
}
```

### 403 Forbidden
```json
{
  "detail": "Inactive user"
}
```

## Next Steps

1. Run database migration: `alembic upgrade head`
2. Test registration endpoint
3. Test login endpoint
4. Test profile endpoints with token
5. Integrate with frontend