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

# API Reference

## Base URL
- Development: `http://localhost:4000`
- 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

### 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>
```

## 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