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

# API Reference

## Base URL
- Development: `http://localhost:3001`
- Production: `https://api.goodgo.com`

## Authentication

All protected endpoints require authentication via:
- **Header**: `Authorization: Bearer <access_token>`
- **Cookie**: `access_token` (HTTP-only)

## Response Format

### Success Response
```json
{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z"
}
```

### Error Response
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message"
  },
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## Endpoints

### Health Check

#### Basic Health
```http
GET /health
```

Returns basic health status for liveness probes.

#### Readiness Probe
```http
GET /health/ready
```

Checks if service is ready to handle requests (includes database connectivity).

#### Liveness Probe
```http
GET /health/live
```

Basic liveness check for container orchestration.

### Authentication

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

{
  "email": "user@example.com",
  "password": "password123",
  "username": "optional"
}
```

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

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

Response includes `accessToken`, `refreshToken`, and `idToken` (OIDC).

#### Logout
```http
POST /api/v1/auth/logout
Authorization: Bearer <token>
```

#### Refresh Token
```http
POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "refresh_token_here"
}
```

Or use cookie: `refresh_token`

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

{
  "currentPassword": "old_password",
  "newPassword": "new_password123"
}
```

#### Get Current User
```http
GET /api/v1/auth/me
Authorization: Bearer <token>
```

### Social Authentication

#### Google OAuth
```http
GET /api/v1/auth/google
```
Redirects to Google OAuth consent screen.

#### Google Callback
```http
GET /api/v1/auth/google/callback?code=<code>&state=<state>
```
Automatically handled by OAuth flow.

Similar endpoints for Facebook and GitHub.

### OIDC

#### Discovery
```http
GET /.well-known/openid-configuration
```

#### Authorize
```http
GET /api/v1/oidc/authorize?client_id=<id>&redirect_uri=<uri>&scope=openid+email+profile&response_type=code
Authorization: Bearer <token>
```

#### Token Exchange
```http
POST /api/v1/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&client_id=<id>&client_secret=<secret>&redirect_uri=<uri>
```

#### UserInfo
```http
GET /api/v1/oidc/userinfo
Authorization: Bearer <token>
```

#### JWKS
```http
GET /api/v1/oidc/jwks
```

### RBAC

#### Get User Permissions
```http
GET /api/v1/rbac/permissions?userId=<optional>
Authorization: Bearer <token>
```

#### Assign Role
```http
POST /api/v1/rbac/roles/assign
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "user_id",
  "roleId": "role_id",
  "expiresAt": "2024-12-31T23:59:59Z" // optional
}
```

#### Revoke Role
```http
POST /api/v1/rbac/roles/revoke
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "user_id",
  "roleId": "role_id"
}
```

#### Grant Permission
```http
POST /api/v1/rbac/permissions/grant
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "user_id",
  "permissionId": "permission_id",
  "expiresAt": "2024-12-31T23:59:59Z" // optional
}
```

#### Check Permission
```http
GET /api/v1/rbac/permissions/check?resource=users&action=read&scope=all
Authorization: Bearer <token>
```

### MFA

#### Enable TOTP
```http
POST /api/v1/mfa/totp/enable
Authorization: Bearer <token>
```

Returns QR code URL and secret.

#### Verify and Enable TOTP
```http
POST /api/v1/mfa/totp/verify
Authorization: Bearer <token>
Content-Type: application/json

{
  "secret": "base32_secret",
  "token": "123456"
}
```

#### Validate TOTP
```http
POST /api/v1/mfa/totp/validate
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "123456"
}
```

#### Disable MFA
```http
POST /api/v1/mfa/disable
Authorization: Bearer <token>
```

#### Get MFA Devices
```http
GET /api/v1/mfa/devices
Authorization: Bearer <token>
```

### Sessions

#### Get User Sessions
```http
GET /api/v1/sessions
Authorization: Bearer <token>
```

#### Revoke Session
```http
DELETE /api/v1/sessions/:sessionId
Authorization: Bearer <token>
```

#### Revoke All Sessions
```http
DELETE /api/v1/sessions
Authorization: Bearer <token>
```

### Identity Management

#### User Management

##### List Users
```http
GET /api/v1/identity/users?organizationId=<id>&isActive=true&emailVerified=true&search=<term>&skip=0&take=20
Authorization: Bearer <token>
```

Returns paginated list of users with filters.

##### Get User
```http
GET /api/v1/identity/users/:id
Authorization: Bearer <token>
```

##### Update User
```http
PUT /api/v1/identity/users/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "new_username",
  "email": "new@example.com",
  "isActive": true,
  "organizationId": "org_id"
}
```

##### Delete User
```http
DELETE /api/v1/identity/users/:id
Authorization: Bearer <token>
```

##### Deactivate User
```http
POST /api/v1/identity/users/:id/deactivate
Authorization: Bearer <token>
```

##### Reactivate User
```http
POST /api/v1/identity/users/:id/reactivate
Authorization: Bearer <token>
```

##### Bulk Import Users
```http
POST /api/v1/identity/users/bulk-import
Authorization: Bearer <token>
Content-Type: application/json

{
  "organizationId": "org_id",
  "users": [
    {
      "email": "user1@example.com",
      "username": "user1",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1234567890"
    }
  ]
}
```

##### Bulk Export Users
```http
GET /api/v1/identity/users/bulk-export?organizationId=<id>&format=csv
Authorization: Bearer <token>
```

#### Profile Management

##### Get Profile
```http
GET /api/v1/identity/users/:id/profile
Authorization: Bearer <token>
```

##### Update Profile
```http
PUT /api/v1/identity/users/:id/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "avatarUrl": "https://example.com/avatar.jpg",
  "customFields": {},
  "preferences": {},
  "metadata": {}
}
```

##### Upload Avatar
```http
POST /api/v1/identity/users/:id/profile/avatar
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <image_file>
```

##### Delete Avatar
```http
DELETE /api/v1/identity/users/:id/profile/avatar
Authorization: Bearer <token>
```

#### Identity Verification

##### Request Email Verification
```http
POST /api/v1/identity/verification/email/request
Authorization: Bearer <token>
```

##### Verify Email
```http
POST /api/v1/identity/verification/email/verify
Content-Type: application/json

{
  "token": "verification_token"
}
```

##### Request Phone Verification
```http
POST /api/v1/identity/verification/phone/request
Authorization: Bearer <token>
```

##### Verify Phone
```http
POST /api/v1/identity/verification/phone/verify
Content-Type: application/json

{
  "token": "verification_token",
  "code": "123456"
}
```

##### Get Verification Status
```http
GET /api/v1/identity/verification/:id/status
Authorization: Bearer <token>
```

#### Organizations

##### List Organizations
```http
GET /api/v1/identity/organizations?skip=0&take=20
Authorization: Bearer <token>
```

##### Create Organization
```http
POST /api/v1/identity/organizations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Organization Name",
  "domain": "example.com",
  "parentId": "parent_org_id",
  "settings": {}
}
```

##### Get Organization
```http
GET /api/v1/identity/organizations/:id
Authorization: Bearer <token>
```

##### Update Organization
```http
PUT /api/v1/identity/organizations/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name",
  "domain": "newdomain.com",
  "isActive": true,
  "settings": {}
}
```

##### Delete Organization
```http
DELETE /api/v1/identity/organizations/:id
Authorization: Bearer <token>
```

##### Get Organization Users
```http
GET /api/v1/identity/organizations/:id/users?skip=0&take=20
Authorization: Bearer <token>
```

#### Groups

##### List Groups
```http
GET /api/v1/identity/organizations/:id/groups?skip=0&take=20
Authorization: Bearer <token>
```

##### Create Group
```http
POST /api/v1/identity/organizations/:id/groups
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Group Name",
  "description": "Group description",
  "organizationId": "org_id"
}
```

##### Get Group
```http
GET /api/v1/identity/groups/:id
Authorization: Bearer <token>
```

##### Update Group
```http
PUT /api/v1/identity/groups/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  "isActive": true
}
```

##### Delete Group
```http
DELETE /api/v1/identity/groups/:id
Authorization: Bearer <token>
```

##### Get Group Members
```http
GET /api/v1/identity/groups/:id/members?skip=0&take=20
Authorization: Bearer <token>
```

##### Add Group Member
```http
POST /api/v1/identity/groups/:id/members
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "user_id",
  "role": "member",
  "expiresAt": "2024-12-31T23:59:59Z"
}
```

##### Remove Group Member
```http
DELETE /api/v1/identity/groups/:id/members/:userId
Authorization: Bearer <token>
```

### Access Management

#### Access Requests

##### List Access Requests
```http
GET /api/v1/access/requests?userId=<id>
Authorization: Bearer <token>
```

##### Create Access Request
```http
POST /api/v1/access/requests
Authorization: Bearer <token>
Content-Type: application/json

{
  "resource": "users",
  "action": "read",
  "reason": "Need access for project",
  "expiresAt": "2024-12-31T23:59:59Z",
  "metadata": {}
}
```

##### Get Access Request
```http
GET /api/v1/access/requests/:id
Authorization: Bearer <token>
```

##### Approve Access Request
```http
PUT /api/v1/access/requests/:id/approve
Authorization: Bearer <token>
Content-Type: application/json

{
  "comments": "Approved for project access"
}
```

##### Reject Access Request
```http
PUT /api/v1/access/requests/:id/reject
Authorization: Bearer <token>
Content-Type: application/json

{
  "comments": "Insufficient justification"
}
```

##### Cancel Access Request
```http
DELETE /api/v1/access/requests/:id
Authorization: Bearer <token>
```

#### Access Reviews

##### List Access Reviews
```http
GET /api/v1/access/reviews?skip=0&take=20
Authorization: Bearer <token>
```

##### Create Access Review
```http
POST /api/v1/access/reviews
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Q4 Access Review",
  "description": "Quarterly access review",
  "type": "PERIODIC",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z"
}
```

##### Get Access Review
```http
GET /api/v1/access/reviews/:id
Authorization: Bearer <token>
```

##### Start Access Review
```http
POST /api/v1/access/reviews/:id/start
Authorization: Bearer <token>
```

##### Complete Access Review
```http
POST /api/v1/access/reviews/:id/complete
Authorization: Bearer <token>
```

##### Get Review Items
```http
GET /api/v1/access/reviews/:id/items?skip=0&take=20
Authorization: Bearer <token>
```

##### Review Access Item
```http
PUT /api/v1/access/reviews/:id/items/:itemId/review
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "APPROVED",
  "comments": "Access is justified"
}
```

#### Access Analytics

##### Usage Analytics
```http
GET /api/v1/access/analytics/usage?startDate=<date>&endDate=<date>
Authorization: Bearer <token>
```

##### Permissions Analytics
```http
GET /api/v1/access/analytics/permissions?resource=<resource>
Authorization: Bearer <token>
```

##### User Access Summary
```http
GET /api/v1/access/analytics/users/:id/summary
Authorization: Bearer <token>
```

##### Risk Analytics
```http
GET /api/v1/access/analytics/risks?minScore=<score>&maxScore=<score>
Authorization: Bearer <token>
```

### Governance & Compliance

#### Compliance Reports

##### List Compliance Reports
```http
GET /api/v1/governance/compliance/reports?type=GDPR&status=PUBLISHED&skip=0&take=20
Authorization: Bearer <token>
```

##### Generate Compliance Report
```http
POST /api/v1/governance/compliance/reports/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "GDPR",
  "name": "Q1 GDPR Report",
  "periodStart": "2024-01-01T00:00:00Z",
  "periodEnd": "2024-03-31T23:59:59Z"
}
```

Supported types: `GDPR`, `SOC2`, `ISO27001`, `HIPAA`, `CUSTOM`

##### Get Compliance Report
```http
GET /api/v1/governance/compliance/reports/:id
Authorization: Bearer <token>
```

##### Export Compliance Report
```http
GET /api/v1/governance/compliance/reports/:id/export?format=pdf
Authorization: Bearer <token>
```

##### Publish Compliance Report
```http
POST /api/v1/governance/compliance/reports/:id/publish
Authorization: Bearer <token>
```

#### Policy Governance

##### Get Policy Templates
```http
GET /api/v1/governance/policies/templates?category=<category>
Authorization: Bearer <token>
```

##### Create Policy Template
```http
POST /api/v1/governance/policies/templates
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Template Name",
  "category": "ACCESS_CONTROL",
  "content": {},
  "description": "Template description"
}
```

##### Get Policy Versions
```http
GET /api/v1/governance/policies/:id/versions
Authorization: Bearer <token>
```

##### Test Policy
```http
POST /api/v1/governance/policies/:id/test
Authorization: Bearer <token>
Content-Type: application/json

{
  "testData": {
    "user": {},
    "resource": {},
    "context": {}
  }
}
```

#### Risk Management

##### List Risk Scores
```http
GET /api/v1/governance/risk/scores?minScore=0&maxScore=100&level=HIGH&skip=0&take=20
Authorization: Bearer <token>
```

##### Get User Risk Score
```http
GET /api/v1/governance/risk/scores/:userId
Authorization: Bearer <token>
```

##### Calculate Risk Score
```http
POST /api/v1/governance/risk/calculate
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "user_id",
  "factors": {}
}
```

##### Risk Dashboard
```http
GET /api/v1/governance/risk/dashboard
Authorization: Bearer <token>
```

#### Reporting

##### Access Summary Report
```http
GET /api/v1/governance/reports/access-summary?startDate=<date>&endDate=<date>
Authorization: Bearer <token>
```

##### User Activity Report
```http
GET /api/v1/governance/reports/user-activity?userId=<id>&startDate=<date>&endDate=<date>
Authorization: Bearer <token>
```

##### Security Events Report
```http
GET /api/v1/governance/reports/security-events?startDate=<date>&endDate=<date>&severity=<level>
Authorization: Bearer <token>
```

##### Compliance Status Report
```http
GET /api/v1/governance/reports/compliance-status?framework=<framework>
Authorization: Bearer <token>
```

##### Risk Overview Report
```http
GET /api/v1/governance/reports/risk-overview?startDate=<date>&endDate=<date>
Authorization: Bearer <token>
```

### Metrics

#### Prometheus Metrics
```http
GET /metrics
```

Returns application metrics in Prometheus format for monitoring.

## Error Codes

- `AUTH_001` - Authentication required
- `AUTH_002` - Invalid or expired token
- `AUTH_003` - Authentication required for authorization
- `AUTH_004` - Insufficient permissions
- `VALIDATION_ERROR` - Input validation failed
- `REGISTRATION_FAILED` - User registration failed
- `LOGIN_FAILED` - Login failed
- `REFRESH_FAILED` - Token refresh failed
- `MFA_REQUIRED` - Multi-factor authentication required
- `RATE_LIMIT_EXCEEDED` - Too many requests
- `INSUFFICIENT_PERMISSIONS` - Permission denied

## Rate Limiting

Rate limits are applied dynamically based on user role:
- **SUPER_ADMIN**: 1000 requests / 15 minutes
- **ADMIN**: 500 requests / 15 minutes
- **MODERATOR**: 300 requests / 15 minutes
- **USER**: 100 requests / 15 minutes
- **Unauthenticated**: 50 requests / 15 minutes

## Security Notes

1. Always use HTTPS in production
2. Tokens are stored in HTTP-only cookies
3. CSRF protection is enabled
4. Rate limiting is enforced
5. Zero-trust validation on all requests
6. Audit logging for all auth events