pos-system/services/iam-service/docs/QUICK_START.md

# Quick Start Guide

## 🚀 Getting Started

### 1. Install Dependencies
```bash
pnpm install
```

### 2. Setup Environment
```bash
cp env.local.example .env.local
# Edit .env.local with your configuration
```

### 3. Setup Database
```bash
# Generate Prisma Client
pnpm prisma:generate

# Run migrations
pnpm prisma:migrate

# Seed database (creates admin user)
pnpm prisma:seed
```

### 4. Start Development Server
```bash
pnpm dev
```

Service will start on `http://localhost:3001`

## 📝 Default Credentials

After seeding:
- **Admin**: `admin@goodgo.com` / `admin123`
- **Test User**: `test@goodgo.com` / `test123`

## 🔑 API Testing

The IAM Service provides 50+ endpoints across 10 modules. Here are quick examples for the main modules:

### Authentication Module
```bash
curl -X POST http://localhost:3001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'
```

### Login
```bash
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@goodgo.com",
    "password": "admin123"
  }'
```

### Get Current User
```bash
curl -X GET http://localhost:3001/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Check Permissions
```bash
curl -X GET "http://localhost:3001/api/v1/rbac/permissions/check?resource=users&action=read&scope=all" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Identity Management Module
Manage users, profiles, organizations, and groups:

```bash
# List users
curl -X GET http://localhost:3001/api/v1/identity/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get user profile
curl -X GET http://localhost:3001/api/v1/identity/users/{userId}/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Access Management Module
Handle access requests, reviews, and analytics:

```bash
# Create access request
curl -X POST http://localhost:3001/api/v1/access/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "users",
    "action": "write",
    "scope": "all",
    "reason": "Need access to manage users"
  }'

# List access requests
curl -X GET http://localhost:3001/api/v1/access/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Governance & Compliance Module
Compliance reporting, risk management, and policy templates:

```bash
# Get risk scores
curl -X GET http://localhost:3001/api/v1/governance/risk/scores \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# List compliance reports
curl -X GET http://localhost:3001/api/v1/governance/compliance/reports \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**For complete API documentation, see [API Reference](API_REFERENCE.md).**

## 🔐 Social Login Setup

### Google OAuth
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create OAuth 2.0 credentials
3. Add to `.env.local`:
   ```
   GOOGLE_CLIENT_ID=your-client-id
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3001/api/v1/auth/google/callback
   ```

### Facebook OAuth
1. Go to [Facebook Developers](https://developers.facebook.com/)
2. Create App and get credentials
3. Add to `.env.local`:
   ```
   FACEBOOK_APP_ID=your-app-id
   FACEBOOK_APP_SECRET=your-app-secret
   FACEBOOK_REDIRECT_URI=http://localhost:3001/api/v1/auth/facebook/callback
   ```

### GitHub OAuth
1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create new OAuth App
3. Add to `.env.local`:
   ```
   GITHUB_CLIENT_ID=your-client-id
   GITHUB_CLIENT_SECRET=your-client-secret
   GITHUB_REDIRECT_URI=http://localhost:3001/api/v1/auth/github/callback
   ```

## 🔒 MFA Setup

### Enable TOTP
1. Call `POST /api/v1/mfa/totp/enable` to get QR code
2. Scan QR code with authenticator app (Google Authenticator, Authy, etc.)
3. Call `POST /api/v1/mfa/totp/verify` with token from app

## 📊 Health Checks

- `GET /health` - Basic health check
- `GET /health/ready` - Readiness probe (checks database)
- `GET /health/live` - Liveness probe

## 🐳 Docker Deployment

```bash
cd ../../deployments/local
docker-compose up -d iam-service
```

## 📚 Documentation

- See `README.md` for full documentation
- See `IMPLEMENTATION.md` for implementation details
- API docs available at `/api-docs` when running

## 🛠️ Troubleshooting

### Database Connection Issues
- Check `DATABASE_URL` in `.env.local`
- Ensure database is running
- Run `pnpm prisma:generate` if schema changed

### Redis Connection Issues
- Check `REDIS_URL` in `.env.local`
- Ensure Redis is running
- Default: `redis://localhost:6379`

### JWT Errors
- Ensure `JWT_SECRET` is set in `.env.local`
- Use strong, random secrets in production
- Never commit secrets to git