admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ae24a7bc87f451d2df45fbb2bead0bf3d8a52ff
pos-system/services/iam-service/docs/API_REFERENCE.md
Ho Ngoc Hai af303eaf7b Enhance IAM Service documentation with comprehensive updates 
- Expanded the IAM Service README to include a detailed overview, features showcase, and quick start guide.
- Updated API reference with new endpoints for health checks and identity management.
- Improved implementation details, including completed features and module dependencies.
- Enhanced architecture documentation with clear diagrams and structured sections for better understanding.
- Added quick reference tables for API endpoints across various modules, improving accessibility for developers.

These changes aim to provide a clearer, more comprehensive understanding of the IAM Service's capabilities and usage.
2026-01-02 00:39:14 +07:00

16 KiB
Raw Blame History

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

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z"
}

Error Response

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

Endpoints

Health Check

Basic Health

GET /health

Returns basic health status for liveness probes.

Readiness Probe

GET /health/ready

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

Liveness Probe

GET /health/live

Basic liveness check for container orchestration.

Authentication

Register

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

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

Login

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

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

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

Logout

POST /api/v1/auth/logout
Authorization: Bearer <token>

Refresh Token

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

{
  "refreshToken": "refresh_token_here"
}

Or use cookie: refresh_token

Change Password

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

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

Get Current User

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

Social Authentication

Google OAuth

GET /api/v1/auth/google

Redirects to Google OAuth consent screen.

Google Callback

GET /api/v1/auth/google/callback?code=<code>&state=<state>

Automatically handled by OAuth flow.

Similar endpoints for Facebook and GitHub.

OIDC

Discovery

GET /.well-known/openid-configuration

Authorize

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

Token Exchange

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

GET /api/v1/oidc/userinfo
Authorization: Bearer <token>

JWKS

GET /api/v1/oidc/jwks

RBAC

Get User Permissions

GET /api/v1/rbac/permissions?userId=<optional>
Authorization: Bearer <token>

Assign Role

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

POST /api/v1/rbac/roles/revoke
Authorization: Bearer <token>
Content-Type: application/json

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

Grant Permission

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

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

MFA

Enable TOTP

POST /api/v1/mfa/totp/enable
Authorization: Bearer <token>

Returns QR code URL and secret.

Verify and Enable TOTP

POST /api/v1/mfa/totp/verify
Authorization: Bearer <token>
Content-Type: application/json

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

Validate TOTP

POST /api/v1/mfa/totp/validate
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "123456"
}

Disable MFA

POST /api/v1/mfa/disable
Authorization: Bearer <token>

Get MFA Devices

GET /api/v1/mfa/devices
Authorization: Bearer <token>

Sessions

Get User Sessions

GET /api/v1/sessions
Authorization: Bearer <token>

Revoke Session

DELETE /api/v1/sessions/:sessionId
Authorization: Bearer <token>

Revoke All Sessions

DELETE /api/v1/sessions
Authorization: Bearer <token>

Identity Management

User Management

List Users
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
GET /api/v1/identity/users/:id
Authorization: Bearer <token>
Update User
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
DELETE /api/v1/identity/users/:id
Authorization: Bearer <token>
Deactivate User
POST /api/v1/identity/users/:id/deactivate
Authorization: Bearer <token>
Reactivate User
POST /api/v1/identity/users/:id/reactivate
Authorization: Bearer <token>
Bulk Import Users
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
GET /api/v1/identity/users/bulk-export?organizationId=<id>&format=csv
Authorization: Bearer <token>

Profile Management

Get Profile
GET /api/v1/identity/users/:id/profile
Authorization: Bearer <token>
Update Profile
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
POST /api/v1/identity/users/:id/profile/avatar
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <image_file>
Delete Avatar
DELETE /api/v1/identity/users/:id/profile/avatar
Authorization: Bearer <token>

Identity Verification

Request Email Verification
POST /api/v1/identity/verification/email/request
Authorization: Bearer <token>
Verify Email
POST /api/v1/identity/verification/email/verify
Content-Type: application/json

{
  "token": "verification_token"
}
Request Phone Verification
POST /api/v1/identity/verification/phone/request
Authorization: Bearer <token>
Verify Phone
POST /api/v1/identity/verification/phone/verify
Content-Type: application/json

{
  "token": "verification_token",
  "code": "123456"
}
Get Verification Status
GET /api/v1/identity/verification/:id/status
Authorization: Bearer <token>

Organizations

List Organizations
GET /api/v1/identity/organizations?skip=0&take=20
Authorization: Bearer <token>
Create Organization
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
GET /api/v1/identity/organizations/:id
Authorization: Bearer <token>
Update Organization
PUT /api/v1/identity/organizations/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name",
  "domain": "newdomain.com",
  "isActive": true,
  "settings": {}
}
Delete Organization
DELETE /api/v1/identity/organizations/:id
Authorization: Bearer <token>
Get Organization Users
GET /api/v1/identity/organizations/:id/users?skip=0&take=20
Authorization: Bearer <token>

Groups

List Groups
GET /api/v1/identity/organizations/:id/groups?skip=0&take=20
Authorization: Bearer <token>
Create Group
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
GET /api/v1/identity/groups/:id
Authorization: Bearer <token>
Update Group
PUT /api/v1/identity/groups/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  "isActive": true
}
Delete Group
DELETE /api/v1/identity/groups/:id
Authorization: Bearer <token>
Get Group Members
GET /api/v1/identity/groups/:id/members?skip=0&take=20
Authorization: Bearer <token>
Add Group Member
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
DELETE /api/v1/identity/groups/:id/members/:userId
Authorization: Bearer <token>

Access Management

Access Requests

List Access Requests
GET /api/v1/access/requests?userId=<id>
Authorization: Bearer <token>
Create Access Request
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
GET /api/v1/access/requests/:id
Authorization: Bearer <token>
Approve Access Request
PUT /api/v1/access/requests/:id/approve
Authorization: Bearer <token>
Content-Type: application/json

{
  "comments": "Approved for project access"
}
Reject Access Request
PUT /api/v1/access/requests/:id/reject
Authorization: Bearer <token>
Content-Type: application/json

{
  "comments": "Insufficient justification"
}
Cancel Access Request
DELETE /api/v1/access/requests/:id
Authorization: Bearer <token>

Access Reviews

List Access Reviews
GET /api/v1/access/reviews?skip=0&take=20
Authorization: Bearer <token>
Create Access Review
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
GET /api/v1/access/reviews/:id
Authorization: Bearer <token>
Start Access Review
POST /api/v1/access/reviews/:id/start
Authorization: Bearer <token>
Complete Access Review
POST /api/v1/access/reviews/:id/complete
Authorization: Bearer <token>
Get Review Items
GET /api/v1/access/reviews/:id/items?skip=0&take=20
Authorization: Bearer <token>
Review Access Item
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
GET /api/v1/access/analytics/usage?startDate=<date>&endDate=<date>
Authorization: Bearer <token>
Permissions Analytics
GET /api/v1/access/analytics/permissions?resource=<resource>
Authorization: Bearer <token>
User Access Summary
GET /api/v1/access/analytics/users/:id/summary
Authorization: Bearer <token>
Risk Analytics
GET /api/v1/access/analytics/risks?minScore=<score>&maxScore=<score>
Authorization: Bearer <token>

Governance & Compliance

Compliance Reports

List Compliance Reports
GET /api/v1/governance/compliance/reports?type=GDPR&status=PUBLISHED&skip=0&take=20
Authorization: Bearer <token>
Generate Compliance Report
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
GET /api/v1/governance/compliance/reports/:id
Authorization: Bearer <token>
Export Compliance Report
GET /api/v1/governance/compliance/reports/:id/export?format=pdf
Authorization: Bearer <token>
Publish Compliance Report
POST /api/v1/governance/compliance/reports/:id/publish
Authorization: Bearer <token>

Policy Governance

Get Policy Templates
GET /api/v1/governance/policies/templates?category=<category>
Authorization: Bearer <token>
Create Policy Template
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
GET /api/v1/governance/policies/:id/versions
Authorization: Bearer <token>
Test Policy
POST /api/v1/governance/policies/:id/test
Authorization: Bearer <token>
Content-Type: application/json

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

Risk Management

List Risk Scores
GET /api/v1/governance/risk/scores?minScore=0&maxScore=100&level=HIGH&skip=0&take=20
Authorization: Bearer <token>
Get User Risk Score
GET /api/v1/governance/risk/scores/:userId
Authorization: Bearer <token>
Calculate Risk Score
POST /api/v1/governance/risk/calculate
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "user_id",
  "factors": {}
}
Risk Dashboard
GET /api/v1/governance/risk/dashboard
Authorization: Bearer <token>

Reporting

Access Summary Report
GET /api/v1/governance/reports/access-summary?startDate=<date>&endDate=<date>
Authorization: Bearer <token>
User Activity Report
GET /api/v1/governance/reports/user-activity?userId=<id>&startDate=<date>&endDate=<date>
Authorization: Bearer <token>
Security Events Report
GET /api/v1/governance/reports/security-events?startDate=<date>&endDate=<date>&severity=<level>
Authorization: Bearer <token>
Compliance Status Report
GET /api/v1/governance/reports/compliance-status?framework=<framework>
Authorization: Bearer <token>
Risk Overview Report
GET /api/v1/governance/reports/risk-overview?startDate=<date>&endDate=<date>
Authorization: Bearer <token>

Metrics

Prometheus Metrics

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
Reference in New Issue View Git Blame Copy Permalink