API Reference

General patterns, authentication methods, and common endpoints used across all DashClicks Backend services.

Base URLs

Development Environment

API Router (Main Gateway): http://localhost:5001
Dashboard Gateway: http://localhost:5000
Internal API: http://localhost:5002
External API: http://localhost:5003
AI Service: http://localhost:5010
General Socket: http://localhost:4000
Conversation Socket: http://localhost:6001
Queue Manager: http://localhost:6002
Notification Service: http://localhost:5008

Service Routing

The API Router (port 5001) proxies requests to appropriate services based on URL patterns:

• /v1/* → Internal API (5002) - DashClicks proprietary features and business logic
• /v1/e/* → External API (5003) - Third-party integrations (Stripe, Twilio, Google, etc.)
• /v1/ai/* → AI Service (5010) - OpenAI integration and AI features
• /v1/currency → Currency Service (5005) - Currency conversion utilities

Authentication

The DashClicks Backend uses session-based authentication with JWT tokens for API requests. The system creates sessions that are identified by session IDs, which in turn contain JWT tokens for authorization.

Primary Authentication Methods

1. Session ID Header (recommended)

X-Session-Id: <session-id>

2. Cookie Authentication

Cookie: sid_dc_sw=<session-id>

3. Query Parameter (Limited use)

GET /endpoint?token=<session-id>

Authentication Flow

1. Login: User authenticates with email/password → Creates ApiSession record
2. Session ID: System returns session ID that maps to stored JWT token
3. API Requests: Client sends session ID in X-Session-Id header
4. Token Validation: System retrieves JWT from session and validates it
5. Authorization: JWT payload contains user permissions and account access

Token Structure (Internal JWT)

• Access Token: Contains user ID, account ID, permissions, and scope
• Refresh Token: Long-lived token for session renewal
• Session Scope: Space-separated permission scopes (e.g., "read write admin")

Security

The session-based approach provides additional security by storing JWT tokens server-side and only exposing session identifiers to clients. This allows for immediate token revocation and centralized session management.

Common Endpoints

GET /status

Service health check endpoint available on all services.

Method: GET
Parameters: None
Authentication: Not required

Example Request:

curl http://localhost:5001/status

Response:

{
  "status": "ok"
}

GET /

Root endpoint providing basic service information.

Method: GET
Parameters: None
Authentication: Not required

Response:

{
  "status": "ok"
}

Error Handling

All DashClicks API endpoints follow consistent error response patterns:

Standard Error Response

interface ErrorResponse {
  errno: number;
  message: string;
  additional_info?: string;
}

Common HTTP Status Codes

Status Code	Description
200	OK - Request successful
400	Bad Request - Invalid or malformed request
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Endpoint or resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Error Response Examples

Authentication Error:

{
  "errno": 401,
  "message": "Authentication required",
  "additional_info": "Valid session ID must be provided"
}

Validation Error:

{
  "errno": 400,
  "message": "Validation failed",
  "additional_info": "Required field 'email' is missing"
}

Rate Limiting

The DashClicks API implements rate limiting to ensure fair usage:

• Rate limits are applied per IP address and per authenticated user
• Different endpoints may have different rate limits
• Rate limit headers are included in responses when limits are in effect

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1635724800

CORS Support

Cross-Origin Resource Sharing (CORS) is configured to allow requests from authorized domains. The specific CORS configuration varies by environment (development vs production).

Response Formats

All API responses follow consistent patterns:

Success Response:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

Error Response:

{
  "errno": 400,
  "message": "Error description",
  "additional_info": "Additional error details"
}

---