[C12] Welcome

Summary

The page an invited person lands on to accept an invitation. It shows what they are being given and by whom, has them confirm their details and accept the terms of use, and on Activate grants the access the invitation holds. It then opens the application in the organisation they were invited to.

Every EMS application that signs in through Entra carries this page at /welcome/{invitationId}. Each invitation is its own welcome, because each one names the organisation to open next. The first one ships in the Admin Portal, behind S04.

Actor & Context

Actor: the invited person.
Frequency: once per invitation.
Precondition: an invitation exists for this person. The person signs in on arrival if they are not signed in already.
Entry point: the redirect at the end of the Entra invitation redemption; the link in the EMS onboarding email; or sign-in to the application while an invitation is pending (AF-4).

Main Flow

  1. The person arrives at /welcome/{invitationId}. If they are not signed in, the application starts the normal Entra sign-in and returns them here.

  2. The page loads the invitation. It belongs to the signed-in person only if the invitation’s OrgUser carries the same oid as the session.

  3. The page shows: the organisation, the role and access level being offered, who sent the invitation and when, and the application’s welcome and training links.

  4. The person confirms or corrects their first name and last name.

  5. The person accepts the terms of use and the privacy notice.

  6. The person selects Activate. The system:

    1. creates the grants the invitation holds — the LinkedOrg and OrgPermission on the target organisation, and the owning-organisation role if one was chosen;

    2. marks the invitation accepted, recording when, and when the terms were accepted;

    3. re-mints the session token so the new access applies at once.

  7. The application switches the session to the invited organisation and opens its home screen.

Alternative Flows

  • AF-1 — Another person’s invitation. The signed-in oid does not match. The page says the invitation was sent to a different account and offers to sign out. It discloses nothing about the invitation: not the organisation, not the role, not the inviter.

  • AF-2 — Already accepted. The page goes straight to the invited organisation’s home screen.

  • AF-3 — Revoked or expired. The page says the invitation is no longer valid and to contact whoever sent it. Nothing is granted.

  • AF-4 — Signed in without the link. After sign-in, a person with a pending invitation for this application is taken to its welcome page. With several pending, the oldest comes first.

  • AF-5 — Leaves without activating. Nothing is granted. The person is signed in with ROLE_USER only, and the invitation stays pending until it expires.

Acceptance Criteria

  • The invitation is shown only to the session whose oid matches its OrgUser. Any other session gets AF-1, with no invitation details in the page or the API response.

  • No grant exists before Activate. After Activate, the grants exist and the session holds the new role without signing in again.

  • Activate records the acceptance time and the terms-acceptance time on the invitation.

  • After Activate, the session’s active organisation is the invited organisation.

  • A revoked or expired invitation grants nothing.

  • Activate can safely run twice: a second call creates no duplicate grants.

  • A signed-in person with a pending invitation is routed to it (AF-4).

API Surface

Planned shapes — not yet implemented.

Call Purpose

GET /api/invitations/mine

Pending invitations for the signed-in oid (AF-4)

GET /api/invitations/{id}

One invitation, only for its own invitee

POST /api/invitations/{id}/accept

Confirmed names and terms acceptance; creates the grants and marks the invitation accepted

POST /api/session/tenant

The existing organisation switch, called with the invited organisation after acceptance

Out of Scope

  • Self-service sign-up. A person reaches this page only through an invitation.

  • Editing contact details beyond the name.

  • Accepting several invitations at once.

Design Anchors

Notes

  • The invitationId in the URL is not a secret. Possession of the link grants nothing; the oid check does. That is why a forwarded email is harmless.

  • The source of the terms-of-use and privacy-notice text is to be decided.

  • An invited person whose session already existed when the invitation was sent must have their token re-minted on activation. The application must not rely on the next sign-in.