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

POST /api/v1/auth/register
Content-Type: application/json

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

Response:

{
  "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

POST /api/v1/auth/login
Content-Type: application/json

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

Response: Same as registration

3. Get Current User Profile

GET /api/v1/auth/me
Authorization: Bearer <your_token>

Response:

{
  "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

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

POST /api/v1/auth/change-password
Authorization: Bearer <your_token>
Content-Type: application/json

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

Response:

{
  "message": "Password changed successfully"
}

Password Requirements

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

Testing with cURL

Register

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

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)

curl -X GET https://your-space.hf.space/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Error Responses

400 Bad Request

{
  "detail": "Email already registered"
}

401 Unauthorized

{
  "detail": "Incorrect email or password"
}

403 Forbidden

{
  "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