Authentication & Authorization

Document Purpose

This document defines the planned authentication and authorization model for the Tripinger API. It explains how identities are created, how users authenticate, how sessions and tokens are handled, how roles and permissions are enforced, and how access differs across traveler, partner, and admin surfaces.

Tripinger serves multiple product surfaces through one core API platform, including the public web app, partner portal, and admin dashboard. Because these surfaces expose different capabilities and risk levels, the platform needs one consistent identity system with clear authorization boundaries rather than separate ad hoc auth logic in each client.

Auth Model Overview

The API should use a centralized identity and access model with these core characteristics:

• One backend-owned authentication system
• JWT-based session access for authenticated API usage
• Refresh-token support for session renewal
• Email/password login support
• OAuth 2.0 social login support
• Role-based access control for broad access categories
• Resource ownership checks for tenant and user isolation
• Separate treatment of traveler, partner, and admin permissions
• Stronger controls for privileged actions such as moderation, verification, payouts, and internal operations

The current API documentation already identifies JWT and OAuth 2.0 support as the planned direction and explicitly states that role-based access control and resource ownership checks should both be supported. It also names traveler, partner, hotel partner, vehicle owner, restaurant partner, guide or activity partner, admin, super admin, and support agent as the main access roles in scope.

Identity Principles

The authentication system should follow these principles:

1. Backend authority Authentication and authorization decisions must be enforced in the API, not trusted to frontend route hiding or client-side role checks alone. This is especially important because the admin dashboard and partner portal expose sensitive operations.

2. One identity foundation, many access contexts The same core identity system should support travelers, partners, and internal staff while still enforcing different role and permission boundaries. The architecture and API docs both treat the API platform as the shared identity boundary across all product surfaces.

3. Least privilege Users should receive only the access required for their current role and account state. A partner account should not gain admin visibility, and a traveler account should not gain supplier controls unless explicitly authorized.

4. Ownership plus role checks Roles alone are not sufficient. The API should also enforce whether the authenticated actor owns or is assigned to the resource being accessed, such as a hotel, vehicle, booking, or moderation queue item. The current API README explicitly calls for both role-based access control and resource ownership rules.

5. Auditability for privileged access Admin actions, partner-verification decisions, and other sensitive operations should be attributable to authenticated identities and logged appropriately. The architecture document calls out auditability for moderation, payouts, and privileged internal actions as a security requirement.

Authentication Methods

The API should support multiple authentication paths because the public web app is expected to support both traditional login and social onboarding, while partner and admin surfaces require secure authenticated access as well.

Email and password

Email/password authentication should be available as a first-class login method. The API README identifies this as part of the auth module baseline together with token refresh, password reset, and account verification.

This method should support:

• registration
• login
• email verification
• forgot-password initiation
• password reset completion
• refresh token renewal
• logout / token invalidation behavior

OAuth 2.0 social login

The current documentation already lists Google, Facebook, and Apple login as planned social sign-in providers. The API should therefore support OAuth 2.0 or provider-equivalent flows through backend-managed callbacks and account linking logic.

Initial provider priority should follow product needs:

1. Google
2. Apple
3. Facebook

This ordering is practical because the public web app explicitly prioritizes traveler signup and login simplicity, and the API already names those providers in scope.

Admin and partner login

Admin and partner users should authenticate through the same backend identity platform, but their authorization state must be evaluated separately from traveler access. The partner portal docs describe an approval-aware access model, and the admin docs require backend-enforced role checks rather than hidden frontend routes.

Supported Actor Types

The API should treat these as distinct identity contexts even if they share a common underlying user record model.

A single person may eventually have more than one access context, but the API should still issue and evaluate permissions explicitly rather than assuming one role implies another.

Roles

The current API documentation already suggests the following role set, which should be treated as the Phase 1 baseline role vocabulary.

Core roles

• traveler
• partner
• hotel_partner
• vehicle_owner
• restaurant_partner
• guide_partner
• admin
• super_admin
• support_agent

These role names may later be normalized for implementation consistency, but the access categories themselves are already part of the approved documentation direction.

Role meaning

Role hierarchy guidance

The API should not rely on a loose “higher role can do everything” model without limits. Instead:

• super_admin may include the broadest internal permissions.
• admin should be limited to approved operational capabilities.
• support_agent should remain narrower than admin.
• specialized partner roles should be narrower than generic internal roles.
• traveler should never inherit partner or admin permissions.

This reduces accidental privilege escalation and matches the documented need for fine-grained admin and partner access control.

Account States

Authentication is not only about who the user is. It is also about whether the account is allowed to perform the next action.

Traveler states

Recommended traveler account states:

• pending_verification
• active
• suspended
• deleted_or_archived

The public web app documentation already expects registration, login, email verification, reset-password flows, and account preferences, which implies at least a basic lifecycle around account activation and access eligibility.

Partner states

The partner portal documentation already defines these suggested partner account states:

• invited
• registered
• onboarding
• pending_verification
• approved
• suspended

The API should enforce these states server-side. For example:

• a registered or onboarding partner may sign in
• a pending_verification partner may access onboarding and document flows
• only an approved partner should gain full listing, availability, pricing, and booking-management permissions
• a suspended partner should lose normal operational access

Admin states

Recommended admin states:

• active
• inactive
• suspended

Internal access should be revocable immediately and should not depend only on UI configuration.

Session and Token Strategy

The architecture document explicitly lists authentication tokens and refresh flows as security-sensitive areas, and the API README names JWT access and refresh secrets as required environment inputs. That makes a token-based session model the expected API design.

Token model

The API should issue:

• a short-lived access token
• a longer-lived refresh token

The access token should be used for normal authenticated API requests. The refresh token should be used only to obtain new access credentials through a dedicated refresh flow.

Recommended token claims

Access tokens should minimally include:

• subject identifier
• role or roles
• account type or access context where helpful
• token issue time
• token expiry
• session or token version where needed

Avoid putting sensitive profile data or mutable business data directly into tokens.

Refresh token handling

Refresh tokens should support:

• rotation on use where practical
• revocation on logout or security events
• invalidation after password reset where appropriate
• invalidation when account status changes materially
• server-side tracking if stronger session control is required

Transport direction

The exact transport mechanism is not fully fixed in the current docs, but the API should choose one consistent model per client class and document it clearly. For browser-based clients, the design should favor secure handling that minimizes token exposure and supports logout, refresh, and revocation predictably.

Auth Flows

The auth module should support the following main flows.

1. Traveler registration

1. User submits registration details.
2. API creates the user record in a non-fully-active or verification-aware state.
3. API initiates email verification where enabled.
4. User verifies the account.
5. API allows authenticated traveler access.

2. Traveler login

1. User submits email/password or social sign-in request.
2. API validates credentials or provider identity.
3. API checks account status.
4. API issues access and refresh credentials.
5. User gains traveler-scoped access to booking, profile, planner, and other authenticated flows.

3. Partner registration and onboarding

1. User creates or receives a partner-capable account.
2. API assigns initial partner identity state.
3. User enters onboarding and document flows.
4. API tracks verification status and role scope.
5. Approval by admin unlocks full supplier functionality.

4. Admin login

1. Internal user submits credentials.
2. API verifies identity and active internal role assignment.
3. API issues authenticated session credentials.
4. API authorizes access only to approved admin routes and actions.

5. Refresh flow

1. Client presents refresh credential.
2. API validates session eligibility.
3. API issues a new access token and, if rotation is enabled, a new refresh token.
4. API rejects invalid, revoked, expired, or mismatched refresh attempts.

6. Forgot password / reset password

1. User requests password reset.
2. API creates a time-bound reset flow.
3. User proves control of the relevant email channel.
4. API accepts the new password.
5. Old sessions may be invalidated depending on policy.

Authorization Model

Tripinger needs more than login. It needs layered authorization because different users interact with different modules and different data scopes. The API README explicitly states that authorization should combine role-based access control with resource ownership rules.

Layer 1: Authentication

Is the caller authenticated?

Layer 2: Role check

Does the caller have a role that is allowed to enter this route or capability area?

Layer 3: Account-state check

Is the account active, approved, verified, or otherwise eligible for this action?

Layer 4: Resource ownership or assignment check

Does the caller own or control the specific resource, or has the platform assigned them permission over it?

Layer 5: Action-specific policy

Is the requested action permitted under business rules, such as verification state, booking state, moderation state, or internal workflow controls?

This layered model is necessary because a hotel partner should not access another hotel partner’s inventory, and an admin support role should not automatically gain finance or super-admin capabilities.

Ownership Rules

Ownership checks should be enforced for any data or action tied to a specific user, partner, or tenant-like scope.

Traveler ownership examples

A traveler may:

• read and update their own profile
• view their own bookings
• manage their own planner drafts
• submit reviews only when eligible
• access their own saved content and preferences

A traveler may not:

• read another traveler’s profile
• view another user’s bookings
• access partner-only inventory controls
• access internal moderation or finance operations

Partner ownership examples

A partner user may:

• manage listings belonging to their own approved partner entity
• update availability and pricing for their own inventory
• view their own bookings and payout-relevant data
• upload and manage their own documents

A partner user may not:

• edit another partner’s listings
• see internal moderation queues by default
• perform admin verification actions
• bypass approval state requirements

Admin ownership and assignment examples

Internal admins may access broader platform data, but not all admin users should access everything. For example:

• a support agent may inspect a booking and add notes
• a moderator may act on review or content issues
• a compliance reviewer may assess partner documents
• a finance-oriented admin may inspect payment problems
• only stronger internal roles should perform high-risk configuration or privileged user-management actions

Permission Strategy

The API should implement permissions in a way that goes beyond raw role strings.

Recommended permission layers

• Role gates for broad module access
• Action permissions for sensitive operations
• Ownership checks for tenant isolation
• State-aware rules for workflows that depend on verification, booking, or moderation states

Example permission groups

Why permissions matter

The admin README already recommends a fine-grained permission model and explicitly warns against relying only on hidden routes. That same principle should apply across the API.

Route Protection Categories

The API should group routes by access sensitivity.

Public routes

No authentication required.

Examples:

• health checks
• public listing search
• public listing detail fetch
• public destination discovery
• login and registration initiation

Authenticated traveler routes

Require authenticated traveler context.

Examples:

• profile
• saved trips
• personal bookings
• planner drafts
• review submission eligibility

Partner routes

Require authenticated partner context plus approval-aware checks where necessary.

Examples:

• onboarding
• listing creation
• availability updates
• booking inbox
• document uploads
• analytics summaries

Admin routes

Require authenticated internal role checks and, where needed, finer permission checks.

Examples:

• partner approval
• listing review
• booking lookup
• payment issue inspection
• moderation actions
• reporting dashboards

Service or internal routes

May require internal service credentials, stronger guards, or non-public exposure patterns for operational workflows.

OAuth Account Linking Strategy

When a user authenticates through social login, the API should determine whether to:

• create a new user
• link to an existing user
• reject the login because of conflicting identity state
• require additional verification or completion steps

This is especially important for partner and admin users, where identity certainty and controlled access matter more than frictionless sign-in alone.

Recommended rules:

• travelers may use password or supported social sign-in
• partner social login may be allowed later if it does not weaken identity control
• admin social login should be introduced only if operational security standards are satisfied

The current documentation confirms social login intent for the public product, but it does not require that every internal role use social auth in Phase 1.

Verification and Trust Flows

Tripinger’s trust model depends on verified suppliers, verified reviews, and operational oversight. That means auth must interact cleanly with verification state.

Email verification

Email verification should be part of account trust for standard user signup flows. The web and API docs both include email verification among expected auth flows.

Partner verification

Partner accounts should not gain full operational access simply because they authenticated successfully. The partner portal already defines onboarding, document submission, pending verification, and approved states, while the architecture and admin docs describe admin review as part of the partner onboarding journey.

Review eligibility tie-in

The API documentation treats verified reviews and review eligibility as system-level concerns. Authorization should therefore also check eligibility context before allowing review creation, not just whether the user is signed in.

Security Controls

The architecture document explicitly identifies authentication tokens, payment verification, admin access boundaries, partner documents, and AI handling as security-sensitive areas. The auth system should therefore include protective controls from the beginning.

Required controls

• Strong password rules and hashing
• Rate limiting on login and reset flows
• Refresh-token validation and revocation controls
• Secure email verification and reset mechanisms
• Backend-only authorization enforcement
• Audit logging for privileged actions
• Immediate access revocation for suspended internal or partner users
• Verified webhook-driven trust in payment-related downstream flows where auth meets booking lifecycle

Additional recommended controls

• device or session tracking for internal users
• suspicious login detection
• brute-force mitigation
• role-change invalidation of active sessions
• optional MFA for admin users in later phases

Module Responsibilities

The auth model should be implemented through clearly separated backend modules.

Auth module

Owns:

• registration
• login
• token issuance
• refresh flow
• password reset
• email verification
• OAuth callback handling

Users module

Owns:

• user profile and identity-linked non-auth account data
• preferences
• public-safe and self-service profile operations

Partners module

Owns:

• partner role assignment context
• onboarding state
• verification state
• partner access readiness

Admin module

Owns:

• internal role assignment
• privileged access checks
• internal operational action boundaries

This separation follows the modular backend direction already described in the API and architecture docs.

Suggested Endpoint Groups

Exact paths may differ, but the auth surface should likely include groups like these:

Public auth endpoints

• POST /auth/register
• POST /auth/login
• POST /auth/refresh
• POST /auth/forgot-password
• POST /auth/reset-password
• POST /auth/logout
• GET /auth/verify-email
• GET /auth/oauth/:provider
• GET /auth/oauth/:provider/callback

Self-service account endpoints

• GET /me
• PATCH /me
• PATCH /me/password
• GET /me/sessions if session management is exposed later

Internal auth-related endpoints

• partner approval state checks
• admin user role or permission lookup
• session invalidation operations for privileged support or security workflows

Error Handling Direction

Auth and authorization errors should be predictable and safe.

Examples of expected response categories

• invalid credentials
• unverified account
• suspended account
• forbidden role
• forbidden resource ownership
• expired refresh token
• invalid reset token
• partner not approved
• internal permission denied

The API conventions document should later define the exact response envelope format, but auth routes should already follow a consistent error taxonomy that clients can handle reliably. The architecture also calls out the importance of documented API standards and security boundaries across these flows.

Testing Priorities

The API README already lists auth flow tests among the highest-priority Phase 1 backend tests.

Minimum Phase 1 auth test coverage

1. user registration
2. email/password login
3. token refresh
4. password reset request and completion
5. route protection for authenticated traveler endpoints
6. partner login with approval-state restrictions
7. admin login and restricted-route enforcement
8. ownership checks on traveler and partner resources
9. role enforcement on privileged admin actions
10. review-submission eligibility enforcement where applicable

High-risk cases to test

• suspended user attempting access
• pending-verification partner attempting operational actions
• partner accessing another partner’s listing
• support agent attempting super-admin action
• expired or revoked refresh token reuse
• social login conflict with existing account identity
• password reset invalidating prior sessions where policy requires it

Environment Variables

The API README already documents key auth-related environment variables, including:

• JWT_ACCESS_SECRET
• JWT_REFRESH_SECRET

Depending on implementation, the auth module may also require:

• OAuth client IDs and secrets per provider
• email verification URL configuration
• password reset URL configuration
• token expiry settings
• trusted frontend origin settings

These values should be documented in the root .env.example once finalized, consistent with the repository-wide configuration pattern described in the current docs.

Assumptions

This document uses the following planning assumptions:

• The Tripinger API is the single backend authority for auth across web, admin, and partner surfaces.
• JWT access and refresh tokens are the intended session model.
• OAuth sign-in support is planned for Google, Facebook, and Apple.
• Authorization combines role-based access control and resource ownership rules.
• Partner access is approval-aware and must not rely only on successful login.
• Admin access must be enforced server-side with fine-grained permissions, not just hidden routes.

Current Status

This document defines the planned authentication and authorization model for the Tripinger API based on the current generated Phase 1 documentation. Exact endpoint paths, token transport details, password policies, provider onboarding details, and MFA decisions should be finalized during implementation, but the centralized auth model, JWT direction, OAuth support, role system, and layered authorization rules described here should be treated as the Phase 1 baseline.