Auth Module

Overview

Swagger-driven developer documentation for authentication, onboarding, guards, token exchange, and current user flow.

Key APIs

Method	Path	Summary
POST	`/api/auth/exchange`	Exchange Cognito authorization code for platform session
POST	`/api/auth/impersonate`	Impersonate another user (Admin/Owner only)
GET	`/api/auth/me`	Get current authenticated user
POST	`/api/auth/onboarding`	Complete user onboarding
POST	`/api/auth/resend-otp`	Resend signup OTP via Brevo HTTP (rate limits apply)
POST	`/api/auth/signup`	Create Cognito signup (suppress Cognito mail) + send backend OTP via Brevo HTTP
POST	`/api/auth/verify-otp`	Confirm signup after backend OTP: Admin Cognito finalize + email_verified

Frontend Usage Flow

Frontend list pages call collection GET endpoints to load tables or summary views.
Create forms submit payloads to POST endpoints and then refresh the list or navigate to the created resource.

POST `/api/auth/exchange`

Summary: Exchange Cognito authorization code for platform session

Operation ID: AuthController_exchange

Tags: Auth

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "code"
  ],
  "properties": {
    "code": {
      "type": "string",
      "description": "Authorization code received from Cognito"
    }
  }
}

Example:

json

{
  "code": "AUTH_CODE_FROM_COGNITO"
}

Responses

200

Token exchange successful

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "accessToken",
    "tokenType"
  ],
  "properties": {
    "accessToken": {
      "type": "string"
    },
    "tokenType": {
      "type": "string"
    }
  }
}

Example:

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer"
}

400

Authorization code is required

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "statusCode",
    "error"
  ],
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "error": {
      "type": "string"
    },
    "message": {
      "type": "object"
    }
  }
}

Example:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid time range"
}

Notes / Constraints

Supported request content types: application/json.

POST `/api/auth/impersonate`

Summary: Impersonate another user (Admin/Owner only)

Operation ID: AuthController_impersonate

Tags: Auth

Security:

bearer

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "targetUserId"
  ],
  "properties": {
    "targetUserId": {
      "type": "string",
      "description": "Target user to impersonate"
    }
  }
}

Example:

json

{
  "targetUserId": "user-123"
}

Responses

200

Impersonation successful

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "accessToken",
    "tokenType"
  ],
  "properties": {
    "accessToken": {
      "type": "string"
    },
    "tokenType": {
      "type": "string"
    }
  }
}

Example:

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer"
}

400

targetUserId is required

No response body.

Notes / Constraints

Supported request content types: application/json.
Swagger declares security requirements for this operation.

GET `/api/auth/me`

Summary: Get current authenticated user

Operation ID: AuthController_me

Tags: Auth

Security:

bearer

Responses

200

Authenticated user details

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "userId",
    "email"
  ],
  "properties": {
    "userId": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "tenantId": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "onboardingRequired": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "userId": "user-123",
  "email": "john@example.com",
  "tenantId": "tenant-123",
  "role": "TENANT_ADMIN",
  "onboardingRequired": false
}

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

POST `/api/auth/onboarding`

Summary: Complete user onboarding

Operation ID: AuthController_onboarding

Tags: Auth

Security:

bearer

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "fullName": {
      "type": "string"
    },
    "tenantName": {
      "type": "string"
    },
    "planId": {
      "type": "string"
    },
    "role": {
      "type": "string"
    }
  }
}

Example:

json

{
  "fullName": "Raj Kumar",
  "tenantName": "Raj Kumar Workspace",
  "planId": "FREE",
  "role": "TENANT_OWNER"
}

Responses

200

Onboarding completed successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "userId",
    "email"
  ],
  "properties": {
    "userId": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "tenantId": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "onboardingRequired": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "userId": "user-123",
  "email": "john@example.com",
  "tenantId": "tenant-123",
  "role": "TENANT_ADMIN",
  "onboardingRequired": false
}

Notes / Constraints

Supported request content types: application/json.
Swagger declares security requirements for this operation.

POST `/api/auth/resend-otp`

Summary: Resend signup OTP via Brevo HTTP (rate limits apply)

Operation ID: AuthController_resendSignupOtp

Tags: Auth

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "email"
  ],
  "properties": {
    "email": {
      "type": "string"
    }
  }
}

Example:

json

{
  "email": "user@company.com"
}

Responses

200

Content-Type: application/json

Schema:

json

{
  "properties": {
    "success": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "success": true
}

Notes / Constraints

Supported request content types: application/json.

POST `/api/auth/signup`

Summary: Create Cognito signup (suppress Cognito mail) + send backend OTP via Brevo HTTP

Operation ID: AuthController_signupSelfServe

Tags: Auth

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "email",
    "password",
    "fullName",
    "planId"
  ],
  "properties": {
    "email": {
      "type": "string"
    },
    "password": {
      "type": "string",
      "description": "User-selected password stored only in Cognito after OTP success (never persisted server-side)"
    },
    "fullName": {
      "type": "string"
    },
    "planId": {
      "type": "string",
      "description": "Plan id from /api/plans"
    }
  }
}

Example:

json

{
  "email": "user@company.com",
  "password": "string",
  "fullName": "Jane Doe",
  "planId": "FREE"
}

Responses

200

OTP sent

Content-Type: application/json

Schema:

json

{
  "properties": {
    "success": {
      "type": "boolean"
    },
    "expiresInSeconds": {
      "type": "number"
    }
  }
}

Example:

json

{
  "success": true,
  "expiresInSeconds": 0
}

Notes / Constraints

Supported request content types: application/json.

POST `/api/auth/verify-otp`

Summary: Confirm signup after backend OTP: Admin Cognito finalize + email_verified

Operation ID: AuthController_verifySignupOtp

Tags: Auth

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "email",
    "otp",
    "password"
  ],
  "properties": {
    "email": {
      "type": "string"
    },
    "otp": {
      "type": "string",
      "description": "6-digit code from email"
    },
    "password": {
      "type": "string",
      "description": "Same password as signup; applied via AdminSetUserPassword after OTP (HTTPS only, not stored server-side)"
    }
  }
}

Example:

json

{
  "email": "user@company.com",
  "otp": "123456",
  "password": "string"
}

Responses

200

Cognito confirmed; frontend should login via hosted Cognito exchange

Content-Type: application/json

Schema:

json

{
  "properties": {
    "success": {
      "type": "boolean"
    },
    "planId": {
      "type": "string"
    },
    "fullName": {
      "type": "string"
    },
    "emailVerified": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "success": true,
  "planId": "string",
  "fullName": "string",
  "emailVerified": true
}

Notes / Constraints

Supported request content types: application/json.

Module Notes / Constraints

Generated from OpenAPI version metadata: 1.0.
3 operation(s) in this module declare explicit Swagger security requirements.
HTTP methods present in this module: POST, GET.
This file is generated from Swagger/OpenAPI and should be regenerated when controller, DTO, or Swagger decorator changes affect the spec.

Auth Module ​

Overview ​

Key APIs ​

Frontend Usage Flow ​

POST /api/auth/exchange ​

Request ​

Responses ​

200 ​

400 ​

Notes / Constraints ​

POST /api/auth/impersonate ​

Request ​

Responses ​

200 ​

400 ​

Notes / Constraints ​

GET /api/auth/me ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

POST /api/auth/onboarding ​

Request ​

Responses ​

200 ​

Notes / Constraints ​

POST /api/auth/resend-otp ​

Request ​

Responses ​

200 ​

Notes / Constraints ​

POST /api/auth/signup ​

Request ​

Responses ​

200 ​

Notes / Constraints ​

POST /api/auth/verify-otp ​

Request ​

Responses ​

200 ​

Notes / Constraints ​

Module Notes / Constraints ​

Auth Module

Overview

Key APIs

Frontend Usage Flow

POST `/api/auth/exchange`

Request

Responses

200

400

Notes / Constraints

POST `/api/auth/impersonate`

Request

Responses

200

400

Notes / Constraints

GET `/api/auth/me`

Responses

200

401

Notes / Constraints

POST `/api/auth/onboarding`

Request

Responses

200

Notes / Constraints

POST `/api/auth/resend-otp`

Request

Responses

200

Notes / Constraints

POST `/api/auth/signup`

Request

Responses

200

Notes / Constraints

POST `/api/auth/verify-otp`

Request

Responses

200

Notes / Constraints

Module Notes / Constraints