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

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

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>

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