Institution verification and tenant status

Institution verification is one of the first real control points in Academia. It sits between department-head login and a fully trusted department rollout.

This page explains the current verification model, the status values the product uses, and how tenant health should be understood operationally.

Why this page exists

The current product does more than ask for a document upload. The frontend checks the verification state after login, and the backend returns tenant-aware user data that can include verification and tenant status information.

That means verification is not just a form step. It is part of the department's operational readiness model.

Fastest route through this guide

1. Read Verification state model to understand the four main states.
2. Read What happens after login to see how the frontend uses that state.
3. Read Tenant status and department health to understand the larger operational meaning.
4. Continue to Onboarding and first setup if you want the full rollout sequence.

Verification state model

The current docs and product behavior already show four main verification states for the department head:

• NOT SUBMITTED
• PENDING
• APPROVED
• REJECTED

These states should be read as an operational queue rather than a one-time form result.

NOT SUBMITTED

The department head has reached the product but has not yet submitted the institution verification document.

What it means:

• the account exists and the user can log in
• the department is not yet fully trusted from a verification perspective
• the platform should keep directing the department head back toward verification completion

PENDING

The document has been submitted and is waiting for review.

What it means:

• the verification requirement is no longer ignored
• the department may still be usable for limited setup work
• rollout decisions should still be made carefully until the review is completed

APPROVED

The verification review has passed.

What it means:

• the department head has cleared the main first-run trust requirement
• the department can move through setup, invitations, and rollout without verification remaining as an open blocker
• staff activation and wider academic operations can proceed with less governance uncertainty

REJECTED

The submitted verification did not pass review and has to be corrected.

What it means:

• the department head needs to return to the verification surface
• rollout confidence should pause until a corrected submission is made
• invitation and readiness decisions should be reviewed before scaling access further

What happens after login

The current frontend behavior already treats verification as part of the post-login startup path.

After the department head logs in:

1. the app loads the authenticated session state
2. the current user profile is refreshed through the auth session endpoints
3. the verification status is checked
4. the user is redirected to the verification surface when the product sees a missing or rejected verification state

This matters because the department head is the first operational owner of the tenant. If that role is incomplete, the whole department rollout is less reliable.

Supported verification submission flow

The current flow already supports document upload as part of the verification path.

What the docs currently confirm:

• the user uploads a verification document after OTP verification and login
• the accepted file types include PDF, JPG, and PNG
• the backend exposes a document submission endpoint for verification

This is why the verification step should be documented as a real workflow, not as a short onboarding footnote.

Tenant status and department health

Verification lives inside a larger tenant-aware model.

The authenticated user profile already includes tenant data such as:

• tenantId
• tenantDomain
• tenant object details such as name, domain, and status
• optional tenantVerification state for department-head-first flows

This is the important operational interpretation:

• verification is about whether the department head has completed the institution-trust requirement
• tenant status is about whether the department itself is healthy and active in the system

The backend work also suggests status enforcement behavior such as reminders, review decisions, and suspended or restricted states when a department is not in good standing.

Practical operating model

The safest way to treat verification and tenant status is as a readiness ladder.

Condition	Practical meaning	Recommended action
Department head not verified	setup ownership exists, but trust is incomplete	finish verification before scaling the rollout
Verification pending	submission exists, but review is still open	continue limited setup and watch for review outcome
Verification approved	the first-run trust requirement is cleared	continue with invitations, staffing, and operational rollout
Tenant health degraded or suspended	the department may face policy or access restrictions	resolve the underlying status issue before expanding academic activity

What department heads should do first

If you are documenting or operating a new department, the cleanest sequence is:

1. verify email and log in
2. submit the institution verification document immediately
3. monitor the verification result until approved
4. review settings, templates, and workflow defaults
5. invite coordinators and advisors
6. invite students after the working staff layer is ready

Common mistakes to avoid in the docs

• Do not describe verification as purely optional. The current product treats it as a real onboarding requirement for the department head.
• Do not describe verification as a full hard lock on every tenant action. The existing behavior is more nuanced than that.
• Do not mix verification status and tenant status into one generic label. They are related, but they describe different things.
• Do not bury tenant status inside developer-only documentation. It affects operational rollout and governance, not just API payloads.

Best page after this one

If you want to do next...	Go here	Why
Continue the first-run rollout	Onboarding and first setup	It places verification in the full department setup order.
See the role that owns this step	Department head	It explains who carries verification and readiness responsibility.
Understand the system shape behind tenant-aware state	Architecture	It shows how frontend session state and backend tenant data fit together.

Best next reads

• Onboarding and first setup
• Department head
• Architecture