Skip to main content

Authentication

First-time workspace setup

Complete Getting Started — Recommended Setup Sequence (steps 1–12 per Recommended setup order, then steps 13–15 in Listings, Bookings, and Tenants) and Onboarding a New Property — Step 7 before you request partner Bearer keys from [email protected]. Configure steps 11–12 (Integrations, Integration field capability, Tenant categories default for integrations) first — operators automating outside partner integrations use Management session after step 3 (Users). After credentials arrive, verify 200 on a Swagger GET /listings Try it out (this page) before production traffic. 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 Request Format and How It Works for Bearer headers, then Verifying your token in Swagger before your first live call. Next guides: Listings & Availability (first read) → Property & Unit Mapping → Creating Bookings; handle 401 / 403 with Error Handling. Operators automating outside partner integrations should read Management session instead. 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: Authentication section cross-reference · API Reference — API guide cross-reference.

All Vivin integration API endpoints are protected by Bearer token authentication. Every request must include a valid API key in the Authorization header.

Request Format​

Pair with other Authentication sections

Use the same Authorization: Bearer header on every integration prefix — inspect live schemas in Try requests in Swagger. Full endpoint map: Authentication section cross-reference.

GET /your-integration/listings HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

How It Works​

Pair with other Authentication sections

Token scope is one integration platform — do not reuse keys across environments. Contrast operator Management session JWTs before wiring automation — operator-only routes such as AI usage return 401 with integration Bearer keys. Full endpoint map: Authentication section cross-reference.

  1. The Vivin team provisions a unique secret token for your integration during onboarding.
  2. Include this token in every API request as a Bearer token in the Authorization header.
  3. The API validates the token against the registered secret for your integration platform.
  4. If valid, the request proceeds and the authenticated integration context is set (your platform identity and associated account).

Verifying your token in Swagger​

Pair with other Authentication sections

Confirm 200 on a GET /listings Try it out before production traffic — then continue to Listings & Availability. Full endpoint map: Authentication section cross-reference.

Your integration’s OpenAPI (Swagger) page on the API host uses the same Bearer scheme as programmatic calls. Open the URL Vivin gave you at onboarding, click Authorize, paste your API key (with or without the Bearer prefix, following the form hint), then expand an operation and use Try it out to confirm you get 200 responses instead of 401 before you wire a client.

Integration Swagger — Bearer authorize control and listings operations ready for Try it out

Step-by-step UI flow: Try requests in Swagger.

Token Properties​

PropertyDetails
FormatOpaque string (treat as a secret)
LifetimeDoes not expire unless rotated by Vivin
ScopeTied to a single integration platform
Rate limitsContact Vivin for details on rate-limiting policies

Error Responses​

Pair with other Authentication sections

Map 401 / 403 to Error Handling — Authentication Errors; inbound webhooks reuse the same secret per Webhooks & Notifications. Full endpoint map: Authentication section cross-reference.

HTTP StatusMeaningAction
401 UnauthorizedToken is missing, malformed, or invalidCheck that you are sending the correct token in the Authorization: Bearer <token> header
403 ForbiddenToken is valid but does not have access to the requested resourceConfirm with Vivin that your token is scoped correctly

Example: 401 Response​

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Security Best Practices​

Pair with other Authentication sections

Rotate compromised keys via [email protected] — see Get Help & Support. Never paste integration Bearer tokens into Core /api Swagger (operator JWT only). Full endpoint map: Authentication section cross-reference.

  • Store your API key in environment variables or a secrets manager - never hardcode it in source code.
  • Use HTTPS for all API calls. HTTP requests will be rejected.
  • If you suspect your token has been compromised, contact Vivin immediately to rotate it.
  • Do not share your token across different systems or environments.

Authentication section cross-reference​

Use this table when one credential 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 Bearer authorization.

API topic / sectionPair with these docs
Request FormatTry requests in Swagger, Listings & Availability (first authorized read)
How It WorksManagement session (operator JWT contrast), AI usage (management JWT only — not integration Bearer keys), Property & Unit Mapping (onboarding before first read)
Verifying your token in SwaggerListings & Availability, Creating Bookings (authorized writes), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1 (operator collections after partner traffic), Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)
Error ResponsesError Handling — Authentication Errors, Webhooks & Notifications (inbound signing)
Security Best PracticesGet Help & Support, Management session — Core API Swagger (JWT-only /api)

| Lockout catch-up after password recovery | Sign-in restored; operator backlog on partner imports | Common Workflows — Lockout catch-up, Management session, Resetting a Management User Password — Step 3 | | Pending manual receipt approval | Recorded bank transfers still pending until Approve payments | Common Workflows — Pending manual receipt approval, Creating Bookings, Finance — Pending manual payments | | Reject/revert mistaken receipts | Duplicate or wrong-booking receipts after Approve | Common Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts, Glossary — Credit note (payment reject/revert) | | Portfolio segmentation by tenant category | Review one tenant segment on imported bookings | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Creating Bookings | | Notification row-click navigation | Partner traffic creates in-app rows operators triage | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Bearer reads after payment overdue alerts | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | First Booking created alerts after token verify | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Portfolio Debt Aging after partner import alerts | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Partner auth vs operator collections Steps 1–6 on imported bookings | | Finance Income status drill-down | Income segments after import settlement | 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 | Collections bars after partner payment schedules | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Authentication guide sections

Related below links partner Bearer authorization 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: Authentication section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Authentication guide sections

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

Documentation map & escalation​

Pair with other Authentication guide sections

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

Companion API guides​

Pair with other Authentication guide sections

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

Upstream & downstream workflows​

Pair with other Authentication guide sections

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

Operator UI & settings​

Pair with other Authentication guide sections

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

Deeper concept reads​

Pair with other Authentication guide sections

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

Deeper workflow reads​

Pair with other Authentication 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: Authentication section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Authentication guide sections

Partner Bearer keys are unaffected by management lockout — operators reconciling imports after sign-in recovery pair with Management session authentication. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: authentication-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Authentication guide sections

Partner POST /bookings creates Layer 1 schedules; operator pending receipts on imported stays pair with Payment Allocation. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: authentication-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Authentication guide sections

Duplicate partner imports and mistaken OTA receipts pair with Payment Allocation — Correcting mistaken receipts. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: authentication-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Authentication guide sections

Integration default tenant category pairs with Settings > Tenant categories before high-volume partner traffic. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: authentication-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Authentication guide sections

Partner Bearer authorization does not replace /notifications row-click — operators triage webhook-driven in-app rows in the management UI after GET /listings succeeds. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Authentication section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Authentication guide sections

Ongoing/Ended payment overdue rows after partner imports — confirm booking balance on operator Transactions before Finance → Overview → Debt Aging. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Authentication section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Authentication guide sections

Upcoming Booking created / Payment received alerts often follow first authorized POST /bookings — pair with operator Processing a New Booking — Step 6. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Authentication section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Authentication guide sections

Partner imports that enqueue payment overdue rows need portfolio Top debtors on Finance → Overview → Debt Aging after single-booking triage — clear amber Pending before KPI sign-off. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Authentication section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner Bearer auth on integration prefixes does not replace operator collections — imported bookings that enqueue payment overdue rows still need Handling a Late Payment — Steps 1–6 in the management UI. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: authentication-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Authentication guide sections

Partner POST /bookings imports may inflate Scheduled segments — reconcile Income chart segment-click with Debt Aging Top debtors before integration sign-off. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Authentication section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Authentication guide sections

Partner-import collections may lag Cash flow forecast month bars until bookings settle — distinct from Income status segments and Dashboard rent due chart. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Authentication section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Authentication guide sections

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

Module documentation hubs​

Pair with other Authentication guide sections

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

  • Audit module — Manual blocks on mapped units that cause authorized availability reads to disagree with Sales (hub)
  • Bookings module — Operator UI for reservations created via POST /bookings (hub)
  • Dashboard module — Post-login Today, Total debt, Vacant Units, and forecast KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range portfolio KPI charts (Overview, Revenue, Occupancy, ADR, RevPAR, Maintenance) with rankings and heatmaps (hub)
  • Listings module — Property wizard, Channels tab, Archived inventory, 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)
  • Finance module — Portfolio ledgers (Overview, Income, Contract Values, Transactions, Payouts, Deposits) with payment approval and deposit settlement (hub)
  • Tenants module — Tenant directory, profile sidebars, With Debt segmentation, and table expand for linked bookings (hub)
  • Sales module — Portfolio availability, monthly rent editing, and channel manager connections (hub)
  • Utilities module — Bills Included ceiling model, Connections, AI bill upload, and tenant overage charges on payment plans (hub)
  • Operations module — Maintenance tickets, cash flows, check-in/out coordination, Draft ticket queues, and linked cash flows (hub)
  • Inbox module — Portfolio-wide WhatsApp workspace with Dashboard bell Inbox sub-tab deep links (hub)
  • Notifications module — Full /notifications history with search, filters, and row-click navigation (hub); Payment overdue alerts when partner traffic creates overdue schedules
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools for portfolio Q&A (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)