Guest and Vendor Access Flows

This document provides end-to-end flow definitions for guest, vendor, planner, admin, and integration access behavior.

Guest invite access

1. Planner or system creates invitation scope for a guest actor or RSVP unit.
2. Tov+ issues a guest invite token scoped to the occasion and allowed events.
3. Guest opens the invite link on {occasion_slug}.tov.plus.
4. Guest app sends the token to api.tovplus.com for validation/exchange.
5. Backend validates token state, expiration, revocation, and occasion match.
6. Backend creates a guest session scoped to the token or returns an equivalent short-lived access token.
7. Guest app fetches allowed occasion/event/module surfaces using guest_principal.
8. Each request evaluates token scope, invitation scope, module enablement, and permissions.
9. Guest can perform low-friction actions such as RSVP, forms, or guest-visible browsing within the granted scope.

Guest QR access

1. Tov+ generates guest-specific QR content through the Publishing capability or invite workflow.
2. QR encodes or references a scoped guest token.
3. Guest scans the QR code.
4. The guest app or mobile browser opens the occasion flow with the QR token.
5. Backend validates the token and exchanges it for a guest session.
6. Requests proceed as ordinary guest_principal requests with the same scope restrictions.

Rules:

• QR access is not a second auth model.
• QR tokens should be short-lived or one-time when the linked action is sensitive.

Optional guest account claim

1. Guest is already in a valid guest session.
2. Guest chooses to claim access for continuity.
3. Guest authenticates through Keycloak.
4. Tov+ resolves or creates the internal user.
5. Tov+ verifies that the authenticated user currently possesses valid guest entitlement.
6. Tov+ creates or activates the user-to-actor link for the claimed guest actor.
7. Future requests may use user_principal instead of guest_principal.
8. Guest can now access the same occasion from another device by logging in.

Rules:

• claim improves continuity; it must not be required for basic guest usage
• claim must not auto-link unrelated actors based on email alone

Vendor invite and login

1. Planner or admin creates vendor actor or vendor organization actor in the occasion.
2. Planner or admin assigns event/module/resource scopes to the vendor actor.
3. Tov+ issues vendor invite to a specific contact.
4. Vendor opens the invite flow on vendors.tovplus.com.
5. Vendor authenticates through Keycloak or creates an authenticated identity there.
6. Tov+ resolves or creates the internal user.
7. Tov+ activates the user-to-vendor-actor link.
8. Vendor app fetches only the occasions, events, modules, and resources granted to that actor.
9. Each vendor request resolves the vendor actor context and enforces permissions.

Rules:

• vendor onboarding may start from an invite token, but durable access is through authenticated user_principal
• vendor app must not expose planner-only surfaces even if the same user has planner access elsewhere unless the current occasion/actor context allows it

Planner login

1. Planner visits dash.tovplus.com.
2. Planner authenticates through Keycloak.
3. Tov+ resolves the internal user and active planner actor link for the selected occasion.
4. Dashboard fetches accessible occasions and permissions.
5. Planner selects occasion and event context.
6. All module and resource actions are evaluated through central permissions.

Admin login

1. Admin visits admin.tovplus.com.
2. Admin authenticates through Keycloak.
3. Tov+ resolves the internal user and verifies admin-level grants.
4. Admin surface loads only after platform-level authorization passes.
5. Security-sensitive admin actions are fully audited.

Rules:

• admin access is not inferred from planner access
• any future support-view or impersonation mode must be explicit and audited

Integration authentication

1. Admin or system registers an integration app in Tov+.
2. Tov+ issues integration credentials and scoped permissions.
3. Integration calls api.tovplus.com using key/secret or derived access token.
4. Backend authenticates the credential and resolves integration_principal.
5. Backend loads explicit integration scopes.
6. Each request is authorized against those scopes and the target occasion/event/module/resource context.
7. All actions are audited to the integration identity and credential id.

Cross-flow guardrails

• Knowing an occasion slug alone must not grant private access.
• Guest flows remain token-first and low-friction.
• Vendor flows require durable authenticated login for ongoing work.
• Planner and admin access always require authenticated user sessions.
• Integrations never bypass the central authorization path.