MCM-29 — Organization Join Requests

← Back to MCM Nexus overview

As an Org Owner,
I want to review and approve or reject requests from people signing up with my organization's email domain,
so that I control who gets access to our MCM subscription details.

Acceptance Criteria

• When someone signs up with an email domain that already has an organization (see MCM-02 — Customer Self-Signup), no account is created yet — a join request is recorded instead, tied to that organization.
• The organization's Owner receives an email notification when a new join request arrives (see Email Templates below).
• The Owner sees a "Pending Join Requests" list on their Nexus dashboard, showing each requester's name, email, and submitted date.
• The Owner can Approve or Reject each request individually.
• Approving a request creates the Keycloak identity and a User record (OrgRole MEMBER), and sends its own welcome email (see Email Templates below) with a temporary password — the new member gets full access to the organization's subscription details, identical to the Owner's, except they cannot review join requests themselves.
• The temporary password expires 24 hours after issuance; if the requester hasn't logged in by then, it no longer works.
• Rejecting a request discards it; no account is ever created for a rejected request.
• A second signup attempt from an email that already has a pending join request is rejected with a clear "a request is already pending for this email" error rather than creating a duplicate request.
• Only one Owner exists per organization; owner transfer/co-owners are out of scope.
• For an Owner-initiated alternative that skips the request/approval step entirely, see MCM-41 — Invite a Teammate to the Organization.

Technical Design

A new OrgJoinRequest entity (organization_id, requester name/email, status PENDING/APPROVED/REJECTED, timestamps) is created by SignupService when the signup email's domain matches an existing Organization.domain, instead of the normal Keycloak/User/License creation path — see MCM-02. A new JoinRequestController/JoinRequestService in mcm-nexus/backend exposes list/approve/reject endpoints scoped to the calling Owner's own organization; approval runs the same Keycloak-identity-plus-temporary-credential creation MCM-02 uses for a brand-new organization, just attaching the new User (OrgRole.MEMBER) to the existing Organization/License instead of creating new ones, and sending its own approval welcome email (see Email Templates below) rather than MCM-02's.

Email Templates

Two distinct emails are sent in this flow — one to the Owner when a request arrives, one to the requester once it's approved.

To the Owner, when a new join request arrives:

Subject: New Request to Join Your Organization on MCM Nexus

Dear <Owner Name>,

Greetings from the MCM Team!

<Requester Name> (<Requester Email>) has requested to join your organization, <Company Name>, on MCM Nexus.

Log in to review this request and either approve or reject it:

Portal: https://nexus.mcm.revdau.ai/dashboard

If you have any questions, our support team is available to help.

Support Email: mcm@revdau.ai
Documentation Portal: https://mcm.revdau.ai/docs/

Thank you for choosing MCM.

Best Regards,
MCM Team

To the requester, once the Owner approves:

Subject: Your Request to Join <Company Name> Has Been Approved

Dear <Requester Name>,

Greetings from the MCM Team!

Your request to join <Company Name> on MCM Nexus has been approved. Use the temporary password below to log in and set your own password.

## Your Login Details

Portal: https://nexus.mcm.revdau.ai/login
Email: <Requester Email>
Temporary Password: <generated password>

This temporary password expires in 24 hours — please log in and set your new password before then.

You'll be asked to set a new password the first time you log in. Once in, you'll have full access to your organization's subscription details.

If you have any questions, our support team is available to help.

Support Email: mcm@revdau.ai
Documentation Portal: https://mcm.revdau.ai/docs/

Thank you for choosing MCM.

Best Regards,
MCM Team

A rejected request sends no email to the requester — they only ever see the initial "sent for approval" confirmation screen (see UI / Frontend Changes below).

UI / Frontend Changes

• New "Pending Join Requests" section on the Owner's Nexus dashboard, listing requester name, email, submitted date, with Approve/Reject actions per row.
• Approve/Reject actions require a confirmation step, since approving grants full subscription-details access and rejecting is final.
• Badge/count indicator in the dashboard nav when pending requests exist, so the Owner notices without checking the list proactively.
• Requester-facing: after submitting a signup for an already-claimed domain, they see an on-screen "Your request has been sent to your organization's Nexus owner for approval" confirmation — no email is sent to the requester at this stage; they're notified by email only once the Owner approves or rejects.

Out of Scope

• Owner transfer or multiple Owners per organization.
• Requester-side visibility into request status beyond the initial confirmation screen.
• Bulk approve/reject actions.