Toju/agents-docs/features/invites-join-requests.md

Invites & Join Requests

Status: Active Last updated: 2026-07-05

Overview

Invite links and join-request approval let users join private or moderated chat-servers without public listing. Spans signaling server REST + HTML invite pages and the product client server-directory invite feature.

Responsibilities

• Server: create time-limited invites, resolve invite metadata, record join requests, notify requesters on moderation decisions.
• Client: create/copy invite links, render invite landing UX, call join API with invite codes/passwords.
• It does NOT own: WebSocket room membership (join_server after REST join succeeds).

Key concepts

• Invite: opaque id mapping to a server; may expire.
• Join request: pending membership when server requires approval.
• request_update: server-pushed WebSocket notification when a moderator approves/denies.

REST API

Invites

Method	Path	Auth	Purpose
POST	/api/servers/:id/invites	Bearer	Create invite (moderator)
GET	/api/invites/:id	Public	Resolve invite metadata + server card
GET	/invite/:id	Public	HTML invite landing page (browser)

Join

Method	Path	Auth	Purpose
POST	/api/servers/:id/join	Bearer	Join with password, invite id, or public access; may create join request

Join requests (moderation)

Method	Path	Auth	Purpose
GET	/api/servers/:id/requests	Bearer (manageServer)	List pending requests
PUT	/api/requests/:id	Bearer (manageServer)	Approve or deny; body { status }

PUT /api/requests/:id validates optional ownerId matches authenticated user, checks manageServer permission, updates status, and sends notifyUser(request.userId, { type: 'request_update', request }).

Client flow

1. Moderator creates invite via ServerDirectoryFacade.createInvite().
2. Recipient opens /invite/:id or deep link; client resolves GET /api/invites/:id.
3. Authenticated user calls POST /api/servers/:id/join with invite payload.
4. On approval-required servers, user waits for request_update or polls requests list (moderator UI).

Related

• server-directory.md — join/leave REST
• authentication.md — bearer on mutations
• signaling.md — join_server after join
• Domain README: toju-app/src/app/domains/server-directory/README.md

Changelog

Date	Change
2026-07-05	Initial cross-context invite/join-request contract