Backend Services

Portal Platform’s backend is built on a microservices architecture, with each service handling specific domain logic. This page provides comprehensive documentation for all backend services.

Service Architecture

All backend services follow consistent patterns:

• RESTful API design with standard HTTP methods
• JWT authentication for secure access
• JSON payloads for requests and responses
• Standardized error handling with clear error codes
• Rate limiting to prevent abuse
• Health check endpoints for monitoring

Authentication Service

Base URL: /api/authn

Overview

The Authentication Service manages user authentication, session management, and token lifecycle.

Endpoints

Register User

Create a new user account.

POST /api/authn/register
Content-Type: application/json
 
{
  "email": "newuser@example.com",
  "password": "SecurePassword123!",
  "name": "John Doe"
}

Login

Authenticate a user and receive JWT tokens.

POST /api/authn/login
Content-Type: application/json
 
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Error Codes

Authorization Service

Base URL: /api/authz

Overview

The Authorization Service handles permission checks and role-based access control (RBAC).

Permission Model

Portal Platform uses a hierarchical permission model:

Organization
  ├─ Owner (all permissions)
  ├─ Admin (manage members, resources)
  ├─ Member (create, edit own resources)
  └─ Viewer (read-only access)

User Service

Base URL: /api/user

Overview

The User Service manages user profiles, preferences, and settings.

Endpoints

Get Profile

Retrieve the authenticated user’s profile.

GET /api/user/profile
Authorization: Bearer {accessToken}

Update Profile

Update user profile information.

PATCH /api/user/profile
Authorization: Bearer {accessToken}
Content-Type: application/json
 
{
  "name": "John Smith",
  "bio": "Updated bio"
}

Rate Limiting

All API endpoints are rate-limited to prevent abuse:

Error Handling

All services return standardized error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      }
    ]
  }
}

Next Steps

• Explore the Agent System for automation
• Review Architecture Overview for system design
• Check out API examples in the GitHub repository