Onboarding

The onboarding module covers new organization registration in Moria, admin/member invitations via email + OTP, and the invite-acceptance endpoint for end users. Two controllers are involved: OnboardingOrganizationController at /organizations and InvitationsController at /invitations. Some endpoints are @Public() (signup, accept-invite); the rest require Bearer JWT plus the appropriate role/permission.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	authentication, organizations, users, acl
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Two paths into Moria: organization self-signup (the founding admin registers their own organization, initial status PENDING) or invitation (an organization admin invites another admin / individual user via email + OTP). The invitee completes onboarding via POST /invitations/accept without Bearer — authentication is done via the email + OTP combination.

Method	Path	Auth	Summary
POST	/v1/organizations/signup	public	Self-signup the first admin + organization (Public)
POST	/v1/invitations	bearer	Send invitation OTP to a list of emails (admin / member / individual)
POST	/v1/invitations/accept	public	Invitee completes their profile and exchanges the OTP (Public)
GET	/v1/invitations	bearer	List invitations (current organization, or all for MORIA)
GET	/v1/invitations/:invitation_id	bearer	Single invitation detail
PATCH	/v1/invitations/:invitation_id	bearer	Update invitation fields (email, role, status, organization)
DELETE	/v1/invitations/:invitation_id	bearer	Cancel an invitation

Auth notes

• Public endpoints set cookie access_token + header Token on successful response — FE can use either. The Token header is exposed via CORS.
• Bearer endpoints accept the JWT via Authorization: Bearer <jwt> or via cookie access_token.
• Unknown fields in the body will be rejected (400) because of forbidNonWhitelisted: true. Make sure FE doesn’t send fields outside the DTO.

---

POST /v1/organizations/signup public

Self-signup: creates the founding admin account along with its organization. Initial admin status is INACTIVE until OTP verification; organization status is PENDING until KYB completes.

public event · ORGANIZATION_ONBOARDED

Request body — OnboardAdminDto

Field	Type	Required	Notes
first_name	string	yes	Admin first name
last_name	string	yes	Admin last name
middle_name	string	optional	Middle name
email	string	yes	Admin login email · must be globally unique
password	string	yes	IsStrongPassword — min 8 chars + mixed combination
phone_number	string	yes	International format (+62…)
name	string	yes	Organization name
logo_id	string	optional	UUID from file-manager (see file-manager module)
organization_email	string	yes	Organization contact email
organization_phone	string	yes	Organization contact phone
official_registration_number	string	optional	Official registration number (NIB / SK)
organization_field	enum INDUSTRY	optional	Business sector (see INDUSTRY enum)
country, province, city, district, subdistrict, village, street	string	yes country/city	Full address; some fields optional
postal_code, rt, rw, building_number, unit_number, label	string	optional	Additional address details
address_type	enum AddressType	optional	Default ORGANIZATION

Example request

{
  "first_name": "Anas",
  "last_name": "Malik",
  "email": "admin@moriafund.com",
  "password": "Password@123",
  "phone_number": "+628123456789",
  "name": "Moria Fund",
  "organization_email": "ops@moriafund.com",
  "organization_phone": "+628123456788",
  "country": "Indonesia",
  "city": "Jakarta",
  "province": "DKI JAKARTA",
  "street": "Jl. Sudirman",
  "district": "Pademangan",
  "organization_field": "finance"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "admin and organization onboarded successfully, otp sent to admin email.",
  "data": {
    "organizationAdmin": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Anas",
      "last_name": "Malik",
      "middle_name": null,
      "email": "admin@moriafund.com",
      "phone_number": "+628123456789",
      "user_type": "organization",
      "user_status": "inactive",
      "profile_image": null,
      "organization_id": "660e8400-e29b-41d4-a716-446655440111",
      "created_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

The response also sets cookie access_token (httpOnly) and header Token. FE must store one of these for subsequent requests. A separate OTP email is sent for admin account activation (see authentication module for verify-otp).

Errors

Status	When
400 Bad Request	Validation failed (weak password, invalid email, missing required field, unknown field)
409 Conflict	Admin email or organization name already registered

Side effects

• Creates rows in users (status INACTIVE), organizations (status PENDING), and addresses.
• Issues an activation OTP via email to the admin’s address.
• Creates the default ACL role for the organization (organization_admin).
• Emits BusinessEvent ORGANIZATION_ONBOARDED (impact HIGH).

---

POST /v1/invitations bearer

Send invitation email + OTP to a list of emails. For each email, the specified role determines the kind of user being created (individual vs admin/member of an organization). Individual and admin emails are processed via two different internal paths.

bearer MORIA, ORGANIZATION, INDIVIDUAL invite-individual-user, invite-organization-admin, invite-moria-admin event · USERS_INVITED

Request body — InviteUserDto

Field	Type	Required	Notes
emails	string[]	yes	List of recipient emails. Each entry must be a valid IsEmail.
role_ids	string[] (UUID)	yes except for individuals	Length MUST match emails. Roles are used for ACL lookup. For a role named individual, the internal path used is different.

Example request

{
  "emails": ["amal@example.com", "siti@example.com"],
  "role_ids": [
    "03be5259-f281-478e-a8d0-e7e825e525f2",
    "03be5259-f281-478e-a8d0-e7e825e525f3"
  ]
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Organization otp sent successfully to emails"
}

In non-production environments, the response also includes data.individual and data.admin with a list of { email, otp } for QA convenience. In production these fields are not returned — FE must not rely on them.

Errors

Status	When
400 Bad Request	role_ids.length !== emails.length, or an invalid email
401 Unauthorized	No Bearer or cookie token
403 Forbidden	Caller’s role doesn’t hold the required permission

---

POST /v1/invitations/accept public

The invitee completes their profile and exchanges email + OTP for an active account. Endpoint is @Public() — FE submits the completed form with the OTP received via email.

public event · INDIVIDUAL_USER_ONBOARDED

Request body — OnboardUserDto (main fields)

Field	Type	Required	Notes
first_name, last_name	string	yes	Basic identity
middle_name	string	optional
email	string	yes	Must match the email that received the OTP
organization_otp	string	yes	OTP from the invitation email
password	string	yes	IsStrongPassword
id_card_number	string	optional	KTP number (16 digits)
education	enum Education	optional	bachelor, master, etc.
mother_name, relatives	string	optional	Additional KYC data
phone_number	string	optional	International format
purpose, source_of_income, montly_income	string	optional	Financial profile
gender	enum Gender	optional	male / female
date_of_birth	date	optional	ISO 8601 (YYYY-MM-DD)
place_of_birth	string	optional
religion	enum Religion	optional
marital_status	enum MaritalStatus	optional
profile_image	string	optional	Profile URL (see file-manager)
country, province, city, district, subdistrict, village, street, postal_code, rt, rw, building_number, unit_number, label	string	optional	Residential address
address_type	enum AddressType	optional	Default INDIVIDUAL

Field name typo

The field montly_income has an intentional typo (should be monthly_income) — kept as-is because mobile clients already consume this name. Don’t rename.

Example request

{
  "first_name": "Aisha",
  "last_name": "Putri",
  "email": "amal@example.com",
  "organization_otp": "234567",
  "password": "Strong@8Password",
  "id_card_number": "3208180302730003",
  "phone_number": "+628156489101",
  "gender": "male",
  "date_of_birth": "1990-01-01",
  "religion": "islam",
  "marital_status": "single",
  "province": "DKI JAKARTA",
  "city": "Jakarta",
  "country": "Indonesia"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "User Onboarded Successfully",
  "data": {
    "user": {
      "id": "770e8400-e29b-41d4-a716-446655440222",
      "first_name": "Aisha",
      "last_name": "Putri",
      "middle_name": null,
      "email": "amal@example.com",
      "phone_number": "+628156489101",
      "user_type": "individual",
      "user_status": "active",
      "profile_image": null,
      "organization_id": "660e8400-e29b-41d4-a716-446655440111",
      "created_at": "2026-05-20T09:15:00.000Z"
    }
  }
}

Errors

Status	When
400 Bad Request	OTP mismatch / expired, validation error, weak password
409 Conflict	Email or identity already in use by another user

Side effects

• Creates a new user (status ACTIVE), address, and links them to the inviting organization.
• Updates invitation.status to ACCEPTED.
• Sets cookie access_token (FE can proceed immediately).

---

GET /v1/invitations bearer

List invitations scoped to the caller’s organization (or all organizations if the caller is MORIA). Supports standard pagination and asc/desc ordering by created_at.

bearer MORIA, ORGANIZATION event · FETCH_ALL_INVITES

Query params — QueryParamsDto

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
order	'asc' | 'desc'	desc	Order by created_at
organization_id	string (UUID)	optional	Only allowed for MORIA users — filters to a specific organization. For ORGANIZATION role, the server always uses the caller’s own org (parameter is overridden).

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "All invited admins fetched successfully",
  "data": {
    "limit": 10,
    "count": 24,
    "currentPage": 1,
    "totalPages": 3,
    "invitations": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440333",
        "email": "amal@example.com",
        "user_type": "individual",
        "organization_id": "660e8400-e29b-41d4-a716-446655440111",
        "role_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
        "status": "invited",
        "created_by": "550e8400-e29b-41d4-a716-446655440000",
        "updated_by": "550e8400-e29b-41d4-a716-446655440000",
        "deleted_by": null,
        "created_at": "2026-05-20T08:45:00.000Z",
        "updated_at": "2026-05-20T08:45:00.000Z"
      }
    ]
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
403 Forbidden	Role is not MORIA/ORGANIZATION

---

GET /v1/invitations/:invitation_id bearer

Single invitation detail. The ID must be a UUID v4 — validated via ParseUUIDPipe.

bearer MORIA, ORGANIZATION event · FETCH_AN_INVITE

Path params

Param	Type	Notes
invitation_id	UUID	Invitation ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "invitation fetched successfully",
  "data": {
    "invitation": {
      "id": "880e8400-e29b-41d4-a716-446655440333",
      "email": "amal@example.com",
      "user_type": "individual",
      "organization_id": "660e8400-e29b-41d4-a716-446655440111",
      "role_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
      "status": "invited",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "updated_by": "550e8400-e29b-41d4-a716-446655440000",
      "deleted_by": null,
      "created_at": "2026-05-20T08:45:00.000Z",
      "updated_at": "2026-05-20T08:45:00.000Z"
    }
  }
}

Errors

Status	When
400 Bad Request	invitation_id is not a UUID
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Invitation not found

---

PATCH /v1/invitations/:invitation_id bearer

Update invitation fields. All fields optional — send only what changed.

bearer MORIA, ORGANIZATION event · UPDATE_AN_INVITE

Request body — UpdateInviteDto

Field	Type	Notes
email	string	New email
user_type	enum UserType	moria, organization, individual
status	enum InvitationStatus	invited, accepted, cancelled, expired
role_id	UUID	Move to another role
organization_id	UUID	Move to another organization

Example request

{
  "status": "expired"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "invitation updated successfully",
  "data": {
    "invitation": { "...": "see shape under GET /:invitation_id" }
  }
}

Errors

Status	When
400 Bad Request	Validation failed (invalid UUID, unknown enum)
401 Unauthorized	Bearer/cookie invalid
403 Forbidden	Role lacks access
404 Not Found	Invitation not found

---

DELETE /v1/invitations/:invitation_id bearer

Cancel an invitation. Soft-cancel — the record remains but status = 'cancelled' and deleted_by is set.

bearer MORIA, ORGANIZATION event · CANCEL_AN_INVITE

Path params

Param	Type	Notes
invitation_id	UUID	ID of the invitation to cancel

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "invitation canceled successfully",
  "data": {
    "invitation": { "...": "same shape as GET /:invitation_id, status now 'cancelled'" }
  }
}

Errors

Status	When
400 Bad Request	invitation_id is not a UUID
401 Unauthorized	Bearer/cookie invalid
403 Forbidden	Role lacks access
404 Not Found	Invitation not found

---

Reference

Enum: UserType

• moria — platform superadmin
• organization — organization admin/member
• individual — end user

Enum: InvitationStatus

• invited — OTP sent, waiting for accept
• accepted — user has onboarded
• cancelled — cancelled by admin
• expired — OTP expired

Standard error envelope

{
  "message": "Role IDs and emails length mismatch",
  "statusCode": 400,
  "error": "Bad Request"
}

message may be a string or an array of strings (especially for multi-field validation errors).

Frequently-seen HTTP codes

• 400 body/query/param validation
• 401 missing / expired token
• 403 role/permission mismatch
• 404 resource not found
• 409 resource already exists
• 500 internal — show generic toast in FE