Invitations and first access

Invitations are the main access-control bridge between department setup and real user activity in Academia. They are not just email notifications. They are the workflow that turns a prepared department into an active department.

Why this page exists

The current product already supports a richer invitation lifecycle than a simple send action. The frontend exposes invitation management in the department-head workspace, public invitation acceptance flows, and first-login password handling. The backend exposes invitation APIs, resend actions, and token-based acceptance.

That means invitation behavior deserves a dedicated guide.

Fastest route through this guide

1. Read Who sends invitations to understand role ownership.
2. Read Invitation management workflow to see the sending and tracking model.
3. Read Acceptance and account activation to understand the invitee journey.
4. Continue to Onboarding and first setup if you want the full department rollout sequence.

Who sends invitations

The department head is the main owner of invitation-driven access during first rollout.

In the current docs and product behavior, the cleanest startup order is:

1. invite coordinators first
2. invite advisors next
3. invite students after the working staff layer exists

This order matters because staff readiness should exist before student workload scales.

Invitation management workflow

The department-head workspace already exposes invitation management as a real operating surface.

The current flow supports:

• single invitation form
• bulk invitation for students
• invitation email preview
• queued or immediate sending
• resend action
• revoke action
• invitation list and state tracking

The main backend family behind this area includes:

• GET /tenant/invitations
• POST /tenant/invitations
• POST /tenant/invitations/:id/resend

Supported invitation states

The current docs already confirm these visible invitation states:

• PENDING
• ACCEPTED
• EXPIRED
• REVOKED

These states should be documented as operational signals, not as passive labels.

PENDING

The invitation has been issued but the recipient has not completed acceptance yet.

What it means:

• the department is waiting on user activation
• the sender may need to monitor whether the invitee actually received and opened the message
• rollout readiness may still be incomplete if key staff accounts remain pending

ACCEPTED

The recipient completed the public acceptance flow.

What it means:

• the backend created the user account from the invitation
• the user can move into login and first-password-change steps
• the invited role can now enter its dashboard and start role-specific work

EXPIRED

The invitation token is no longer usable.

What it means:

• the recipient cannot finish activation through that old link
• the sender should decide whether the user still needs access
• resend is usually the cleanest recovery path when the access decision still stands

REVOKED

The invitation was intentionally withdrawn.

What it means:

• the department no longer intends that pending invite to be used
• the old token should not be treated as valid access
• a new invitation is required if the user should be allowed in later

Acceptance and account activation

The invitation acceptance path is public-facing and token-based.

The current sequence is:

1. the invitee opens the public acceptance link
2. the frontend previews invitation details from the token
3. the invitee confirms acceptance
4. the backend creates the user account and returns a temporary password once
5. the invitee logs in
6. the product forces a password change on first login

This is the core reason invitations should be treated as account activation workflows instead of just email delivery events.

Public acceptance routes and proxy behavior

The frontend already uses same-origin routes for public invitation acceptance helpers.

Current examples include:

• /api/invitations/accept/preview
• /api/invitations/accept

These routes matter because invitation acceptance is public, token-based, and sensitive to browser or CORS complexity. The same-origin proxy pattern keeps the public flow stable while forwarding the request to the backend.

First-login expectations for invitees

Invitees do not arrive in the product the same way the department head does.

Their practical first-access sequence is:

1. accept the invitation
2. receive the temporary password once
3. log in with the temporary credential
4. complete the forced password change
5. land in the role-specific dashboard and begin normal work

This matters in the docs because each role page assumes the invitation has already been accepted and the initial password reset is done.

Operational guidance for department heads

The most useful invitation checklist is:

1. verify the department is ready before sending large batches
2. invite coordinators and advisors before broad student rollout
3. use bulk invitation only where it matches the role and workflow
4. monitor pending, expired, and revoked states instead of assuming email delivery means activation
5. resend or revoke deliberately so the invitation list remains trustworthy

Common mistakes to avoid in the docs

• Do not describe invitations as only an email feature. They are an access-control workflow.
• Do not skip the public acceptance step. That is where the account actually becomes real.
• Do not forget the temporary-password-once behavior. It affects onboarding and support expectations.
• Do not assume a sent invitation means a ready user. Pending and expired states still require action.

Best page after this one

If you want to do next...	Go here	Why
Continue the full department rollout	Onboarding and first setup	It places invitations inside the first-run operating sequence.
Understand who owns invitation readiness	Department head	It explains why the department head controls this workflow first.
See what users do after activation	Roles and dashboards	It maps accepted invitees into their real dashboard surfaces.

Best next reads

• Onboarding and first setup
• Department head
• Roles and dashboards