Seller Orchestra Internal API Mapping

Authentication & Session Management

Complete 3-layer API flow for seller authentication, session management, and password operations

3-Layer Architecture

Seller API Gateway Public
Seller Admin Orchestration
User Service Core Microservices

Gateway-Level Token Validation

JWT token validation is performed at the Seller API Gateway level using Keycloak/JWT library. Tokens are validated before requests are forwarded to the Orchestra layer. Session data is cached in Redis with 1-hour TTL.

Future Architecture Note

Currently, all authentication and registration logic resides in the Seller Admin orchestration layer. In future releases, this will be migrated to a dedicated Seller Onboarding & Setup Microservice (Orchestra Layer) for better separation of concerns.

Seller Login

Authenticate seller with multiple methods (email/phone/OTP/social)

POST
Seller API Gateway
POST /merchant/api/v1/auth
Body: { mode, username, password, device_info }
Seller Admin
POST /merchant/api/v1/auth

Login Flow:

  1. Validate login payload (mode, username, password)
  2. Call User Service for authentication
  3. Receive JWT token and user data with domains/permissions
  4. Cache user data in Redis (1-hour TTL)
  5. Return token in response header

Auth Modes: EMAIL_PASSWORD, MOBILE_PASSWORD, EMAIL_OTP, MOBILE_OTP, SOCIAL

Core Microservices
1 POST /auth User Service · Core Microservices

Get Current User / Verify Session

Validate token and retrieve current user details with domains/permissions

GET
Seller API Gateway
GET /merchant/api/v1/auth
Headers: { token: "JWT_TOKEN" }
Seller Admin
GET /merchant/api/v1/auth

Verification Flow:

Note: JWT token validation happens at Gateway level (not via internal API call)

  1. Gateway validates JWT token (Keycloak/JWT library)
  2. Check Redis cache for user session data
  3. If cached, return cached user data
  4. If not cached, fetch from User Service
  5. Cache result in Redis (1-hour TTL)
  6. Return user with domains and permissions
Core Microservices
1 GET /auth User Service · Core Microservices

Logout

Terminate user session and invalidate token

DELETE
Seller API Gateway
DELETE /merchant/api/v1/auth
Query: ?deleteAccount=true (optional - to delete account)
Seller Admin
DELETE /merchant/api/v1/auth
Core Microservices
1 DELETE /auth User Service · Core Microservices

Forgot Password

Reset password using OTP verification

POST
Seller API Gateway
POST /merchant/api/v1/forgot_password
Body: { email, phone, event, passcode_id, new_password }
Seller Admin
POST /merchant/api/v1/forgot_password

Validates passcode before password reset

Core Microservices
1 POST /forgot_password User Service · Core Microservices

Generate Passcode/OTP

Generate OTP for phone/email verification

POST
Seller API Gateway
POST /merchant/api/v1/passcode
Body: { phone, email, ttl, event }
Seller Admin
POST /merchant/api/v1/passcode

Publishes Kafka event: SEND_OTP for SMS/Email delivery

Core Microservices
1 POST /passcode User Service · Core Microservices

Validate Passcode/OTP

Validate OTP for verification flows

POST
Seller API Gateway
POST /merchant/api/v1/passcode/validate
Body: { validate, id, passcode, email, phone, event }
Seller Admin
POST /merchant/api/v1/passcode/validate
Core Microservices
1 POST /passcode/validate User Service · Core Microservices

Update Profile

Update user profile information

PUT
Seller API Gateway
PUT /merchant/api/v1/profile
Body: { first_name, last_name, email, phone, image_url, locale, ... }
Seller Admin
PUT /merchant/api/v1/profile

Validates passcode for email/phone updates, clears Redis cache

Core Microservices
1 PUT /profile User Service · Core Microservices

Change Password

Change password (requires current password)

PUT
Seller API Gateway
PUT /merchant/api/v1/security
Body: { current_password, new_password }
Seller Admin
PUT /merchant/api/v1/security
Core Microservices
1 PUT /security User Service · Core Microservices

List Active Sessions

Get all active sessions with device information

GET
Seller API Gateway
GET /merchant/api/v1/domains/:domain_id/sessions
Seller Admin
GET /merchant/api/v1/domains/:domain_id/sessions

Returns device info, IP, last activity timestamp

Core Microservices
1 GET /sessions User Service · Core Microservices

Revoke Session

Terminate a specific session by ID

DELETE
Seller API Gateway
DELETE /merchant/api/v1/domains/:domain_id/sessions/:session_id
Seller Admin
DELETE /merchant/api/v1/domains/:domain_id/sessions/:session_id
Core Microservices
1 DELETE /sessions/:session_id User Service · Core Microservices

Authentication Features

JWT-based authentication via Keycloak, multi-factor authentication support (OTP), session tracking with device information, and secure password management.

JWT + Keycloak - OTP via SMS/Email - Device Tracking - Redis Sessions