Skip to main content

Management session authentication

First-time workspace setup

Property managers scripting against the Core API should complete Getting Started — Recommended Setup Sequence steps 1–3 (General information, Users, Preferences) before wiring POST /auth/login — this is operator JWT auth, not partner Authentication Bearer keys. Finish steps 4–15 and Onboarding a New Property — Step 7 before portfolio-wide automation touches live bookings. When sign-in was restored mid-setup, see Getting Started — Lockout catch-up after password recovery (refresh Bearer JWT before MCP or scripted calls resume). Guide pairing after go-live: Setup sequence after go-live (hub: API Reference — Setup sequence after go-live).

Finding your way in this guide

Start with How it differs from integration auth and Sign-in flow, then Authenticated API calls for curl examples. Contrast Authentication (partner Bearer keys on integration prefixes). For scripted retries after expiry, see Error Handling on 401 refresh failures. External AI clients: Landlord MCP alternative. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Handling a Late Payment collections, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Management session section cross-reference · API Reference — API guide cross-reference.

This page documents operator authentication for the Vivin Core API — the same session the management frontend uses at platform.vivin.app. It is not the partner integration Bearer token used for GET /{platform}-integration/listings and similar routes.

Use this when you build internal automation, one-off scripts, or evaluate HTTP routes before wiring Landlord MCP. For production AI clients, prefer Landlord MCP tools (they enforce the same permissions as the UI).

How it differs from integration auth​

Pair with other Management session sections

Partner integrations use long-lived Bearer keys — Authentication. Never paste integration keys into Core /api Swagger below. Full endpoint map: Management session section cross-reference.

AspectManagement sessionPartner integration
WhoProperty managers, Vivin internal operatorsChannel managers, OTAs, booking engines
CredentialEmail + password → short-lived JWT in response bodyLong-lived API key in Authorization: Bearer
RefreshhttpOnly cookie (POST /auth/refresh) — not readable from JavaScriptKey does not rotate unless Vivin rotates it
ScopeUser role + accountId on every domain routeSingle integration platform + account
Docs surfaceCore API Swagger at /api when enabled (see below)Per-integration Swagger at /{platform}-integration

Sign-in flow​

Pair with other Management session sections

Browser clients rely on httpOnly refresh cookies — command-line scripts need curl -c cookies.txt -b cookies.txt. Session UX: Getting Started — Staying signed in. Full endpoint map: Management session section cross-reference.

POST /auth/login HTTP/1.1
Host: api.vivin.app
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response (200) — short-lived access token plus user and account context:

{
  "token": "<JWT>",
  "user": {
    "id": "…",
    "email": "[email protected]",
    "firstName": "…",
    "lastName": "…",
    "role": "…",
    "accountId": "…"
  },
  "account": {
    "id": "…",
    "companyName": "…",
    "logoUrl": "…"
  }
}

The server also sets an httpOnly refresh cookie on the response. Browser clients (the management frontend) send that cookie automatically on POST /auth/refresh. Command-line scripts must preserve cookies between requests (for example curl -c cookies.txt -b cookies.txt).

Command-line example (login + refresh cookie)​

Replace api.vivin.app with your API host (http://localhost:3000 when running Core API locally):

# 1) Sign in — save Set-Cookie refresh token to a jar and read the access JWT
curl -sS -c cookies.txt -X POST 'https://api.vivin.app/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"your-password"}' \
  | tee login.json

export VIVIN_JWT="$(jq -r .token login.json)"

# 2) Call a protected route
curl -sS -b cookies.txt -H "Authorization: Bearer ${VIVIN_JWT}" \
  'https://api.vivin.app/bookings?limit=5'

# 3) When the JWT expires, refresh (cookie only — no body)
curl -sS -b cookies.txt -c cookies.txt -X POST 'https://api.vivin.app/auth/refresh' \
  | tee refresh.json

export VIVIN_JWT="$(jq -r .token refresh.json)"

# 4) End the session server-side
curl -sS -b cookies.txt -c cookies.txt -X POST 'https://api.vivin.app/auth/logout'

The refresh cookie name and attributes are managed by Core API — treat cookies.txt as a secret alongside the JWT.

Authenticated API calls​

Pair with other Management session sections

Refresh with POST /auth/refresh when JWT expires — 401 patterns in Error Handling. Permission matrix: Users and roles. Full endpoint map: Management session section cross-reference.

Send the access token on every protected route:

GET /bookings HTTP/1.1
Host: api.vivin.app
Authorization: Bearer <JWT>

When the JWT expires, call POST /auth/refresh with the refresh cookie (no body, no access token required). A successful refresh returns a new token in the body and rotates the refresh cookie.

POST /auth/logout revokes the current refresh token and clears the cookie. Safe to call even when the access token is already expired.

Operator-visible behaviour (silent refresh, session-expired message, sidebar Logout) is described in Getting Started — Staying signed in.

sequenceDiagram
  participant Client as Script or browser
  participant API as Core API
  Client->>API: POST /auth/login (email + password)
  API-->>Client: 200 body.token (JWT) + Set-Cookie refresh
  Client->>API: GET /bookings Authorization Bearer JWT
  alt JWT expired
    Client->>API: POST /auth/refresh (refresh cookie)
    API-->>Client: 200 new token + rotated cookie
    Client->>API: Retry protected route with new JWT
  end
  Client->>API: POST /auth/logout (refresh cookie)
  API-->>Client: Refresh revoked; cookie cleared

Permissions and multi-tenancy​

Pair with other Management session sections

Every route filters by signed-in accountId — same tenancy model as partner reads after Property & Unit Mapping. Do not reuse management JWTs on integration prefixes. Full endpoint map: Management session section cross-reference.

Every management route is scoped to the signed-in user's accountId. Module tabs and write actions additionally require role permissions (for example finance.approve_payments, bookings.create) — the same matrix documented under Users and roles.

401 / 403 responses follow the patterns in Error handling. Integration partners should not reuse management JWTs on integration route prefixes, and vice versa.

Core API Swagger (/api)​

Pair with other Management session sections

Enable locally with ENABLE_CORE_API_SWAGGER=true — integration Swagger stays separate per Try requests in Swagger. Paste JWT from POST /auth/login, not partner Bearer keys. Full endpoint map: Management session section cross-reference.

The internal Core API catalogue (all management and domain routes) is exposed at /api on the API host when ENABLE_CORE_API_SWAGGER=true (or 1) on that environment. It may be disabled on production hosts.

Integration Swagger pages (/uniplaces-integration, /ical-integration, etc.) stay enabled separately — see Try requests in Swagger.

To explore management routes locally:

  1. Start Core API with ENABLE_CORE_API_SWAGGER=true.
  2. Open http://localhost:3000/api.
  3. Click Authorize, choose the Bearer scheme, and paste the JWT from POST /auth/login (with or without the Bearer prefix, per the form hint).
  4. Expand a tag (for example bookings) and use Try it out on a GET you have permission to call.

The Bearer control uses the same JWT as programmatic management calls — not your integration API key. Integration Swagger pages (/{platform}-integration) remain separate; see Try requests in Swagger.

Production and staging hosts

On shared API hosts (for example api.vivin.app), /api may return 404 when ENABLE_CORE_API_SWAGGER is not set. Integration Swagger URLs stay available for partners. Operators evaluating management routes on those hosts should use the management UI, Landlord MCP, or a local Core API instance with Swagger enabled.

Landlord MCP alternative​

Pair with other Management session sections

Prefer Landlord MCP for external AI clients — same permissions as the UI without raw HTTP. Booking-scoped automation: Tenant MCP. Full endpoint map: Management session section cross-reference.

Landlord MCP wraps the same Core API behind MCP tools with session-based auth (Mcp-Session-Id). Prefer MCP when external AI clients need structured, permission-aware tool calls instead of raw HTTP.

Authentication paths for Landlord MCP:

PathWhen to use
API keysIDE assistants (Cursor, Claude Desktop), custom scripts — paste Bearer token from AI / MCP
MCP OAuthHosted connectors (Claude.ai, ChatGPT) — PKCE authorization code on the Core API host
POST /auth/login (this page)One-off scripts and Swagger exploration — refresh via httpOnly cookie

Connector OAuth issues the same management JWT shape as login; see MCP OAuth — Token response.

Management session section cross-reference​

Use this table when one operator-auth topic naturally leads into another API guide, operator UI, or downstream workflow — each row links to the docs you should read before or after wiring management HTTP automation.

API topic / sectionPair with these docs
How it differs from integration authAuthentication, Integrations & Distribution
Sign-in flowGetting Started — Staying signed in, Resetting a Management User Password
Authenticated API callsError Handling, Users and roles, AI usage (LLM cost ledger on same JWT), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1 (management alert routes), Payment Allocation — Correcting mistaken receipts, Glossary — Invoiced floor (rent)
Permissions and multi-tenancyProperty & Unit Mapping (accountId scope), Management Frontend Deep Links
Core API Swagger (/api)Try requests in Swagger, Authentication (integration contrast)
Landlord MCP alternativeLandlord MCP, MCP OAuth (Claude/ChatGPT connectors), Automation & AI

| Lockout catch-up after password recovery | Sign-in restored; JWT scripts must refresh | Common Workflows — Lockout catch-up, Sign-in flow, Resetting a Management User Password — Step 3 | | Pending manual receipt approval | Scripted Finance reads show pending until approval | Common Workflows — Pending manual receipt approval, Finance — Pending manual payments, Payment Allocation | | Reject/revert mistaken receipts | Duplicate receipts from scripted imports | Common Workflows — Reject/revert mistaken receipts, Finance — Row actions on in-payment rows, Glossary — Credit note (payment reject/revert) | | Portfolio segmentation by tenant category | JWT portfolio reads by tenant segment | Common Workflows — Portfolio segmentation, Bookings — Other filters, Finance — Tenant category filter | | Notification row-click navigation | JWT sessions vs /notifications row-click | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Operator UI vs payment overdue | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Management JWT vs confirmation alerts | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Core API reads vs Debt Aging | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Integration surface vs operator collections Steps 1–6 | | Finance Income status drill-down | JWT Finance reads vs Income modals | API Reference — Finance Income status drill-down, Common Workflows — Finance Income status drill-down, FAQ — Finance Income status drill-down hub | | Cash flow forecast drill-down | Operator forecast drill-down | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Management session guide sections

Related below links operator JWT and refresh cookies to setup, companion API guides, operator workflows, and escalation paths. Pair Setup sequence after go-live with Getting Started — Recommended Setup Sequence; pair Companion API guides with API Reference hub. Topic-to-guide pairing in sections above: Management session section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Management session guide sections

Complete Account Settings — Recommended setup order before partner traffic. Hub parity: API Reference — Setup sequence after go-live. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Documentation map & escalation​

Pair with other Management session guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Management session section cross-reference.

Companion API guides​

Pair with other Management session guide sections

Companion guides share Bearer authorization or error shapes with this page — start from API Reference hub. Full pairing matrix: Management session section cross-reference.

  • Authentication (integration) — Partner Bearer keys for marketplace and booking-engine feeds
  • AI usage — Account-scoped LLM token ledger (GET /ai-usage, GET /ai-usage/summary) on the same management JWT
  • Error handling — Standard HTTP error shapes and 401 refresh failures
  • Creating Bookings — Partner write surface (distinct from operator JWT on management routes)
  • Webhooks & Notifications — Outbound events when automation listens instead of polling management GETs
  • Property & Unit Mapping — Partner externalId scope contrast with operator accountId JWT routes

Upstream & downstream workflows​

Pair with other Management session guide sections

Workflow bullets pair with Common Workflows — Workflow cross-reference after partner traffic lands in the management app. Full pairing matrix: Management session section cross-reference.

Operator UI & settings​

Pair with other Management session guide sections

Operator UI rows validate the same inventory and permissions behind integration HTTP — pair with Account Settings — Tab cross-reference. Full pairing matrix: Management session section cross-reference.

Deeper concept reads​

Pair with other Management session guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Management session guide sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each workflow sub-guide also has its own Deeper API reads subsection with reciprocal companion API anchors — hub parity: API Reference — Deeper workflow reads. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Management session guide sections

JWT refresh after password recovery pairs with Resetting a Management User Password — Step 3 before scripted portfolio reads resume. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: management-session-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Management session guide sections

Scripted Finance reads after GET /bookings/cache may still show pending until operators Approve payments — pair with Payment Allocation. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: management-session-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Management session guide sections

Operator JWT scripts that bulk-record receipts pair with Finance — Row actions on in-payment rows when duplicates need Reject / Revert. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: management-session-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Management session guide sections

JWT portfolio filters should align Tenant category across Bookings, Finance, and Tenants — pair with Settings > Tenant categories. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: management-session-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Management session guide sections

Management JWT unlocks operator /notifications row-click — integration Bearer keys cannot triage in-app rows via partner HTTP alone. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Management session guide sections

Operator JWT required for payment overdue row-click into booking Transactions — partner tokens do not open management receivables UI. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Management session guide sections

Refresh management JWT before Upcoming confirmation alert triage — Management session after lockout catch-up. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Management session guide sections

Portfolio Debt Aging reads use management JWT — pair Core /api Finance routes with operator receivables triage after imports. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Management Session do not replace operator collections — payment overdue in-app rows still need Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: management-session-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Management session guide sections

Income segment-click modals require operator session — contrast with integration Bearer GET /listings catalogue reads. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Management session guide sections

Cash flow forecast bar-click drill-down is management-UI only — poll Finance Overview with JWT, not partner integration keys. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Management session section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Management session guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Management session section cross-reference.

Module documentation hubs​

Pair with other Management session guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Management session section cross-reference.

  • AI Chat module — In-management assistant using the same operator JWT session as management HTTP routes (hub)
  • Bookings module — Operator UI routes that share the same JWT session as management scripts (hub)
  • Finance module — Ledger tabs that require Approve payments permission on top of a valid session (hub)
  • Inbox module — WhatsApp routes that require the same operator session as management scripts (hub)
  • Dashboard module — Same-day KPI snapshot using management JWT routes (hub)
  • Operations module — Ticket and cash-flow routes behind the same JWT session as management scripts (hub)
  • Notifications module — Alert routes automation may poll after management JWT sign-in (hub); Payment overdue alerts when scripted queries surface unpaid schedules
  • Audit module — Portfolio-wide Manual Blocks and Discounts contract-value review (hub)
  • Analytics module — Month-range portfolio KPI charts with rankings and heatmaps (hub)
  • Listings module — Property wizard, Channels tab, and unit management (hub)
  • Properties workspace — Legacy /properties URL redirects into Listings (hub)
  • Booking engine details — Rich marketplace payload editor via the Full integration pill (hub)
  • Tenants module — Tenant directory and profile sidebars (hub)
  • Sales module — Portfolio availability and channel manager connections (hub)
  • Utilities module — Bills Included ceiling model and tenant overage charges (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)