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. Habit-specific shortcuts live under Related below.

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.

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.

  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.

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.

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).

  • 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 the endpoints and fields above. Related integrator pages are linked inline where useful.

Pair with other Authentication guide sections

Related below links partner Bearer authorization to setup, companion API guides, operator workflows, and escalation paths.

Setup sequence after go-live​

Pair with other Authentication guide sections

Complete Account Settings — Recommended setup order before partner traffic.

Documentation map & escalation​

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.

Upstream & downstream workflows​

Operator UI & settings​

Deeper concept reads​

Deeper workflow reads​

See Upstream & downstream workflows above for the same guides.

Operator habit hubs​

Day-to-day operator habits (lockout catch-up, pending receipts, payment triage, handoffs, and related playbooks) live on the Common Workflows habit hub.

Deep-link anchors for habit hubs

Lockout catch-up after password recovery​

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​

Key glossary terms​

Module documentation hubs​

Pair with other Authentication guide sections

for screen-by-screen operator follow-up.

  • 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 — AI Assistant using Landlord MCP tools for portfolio Q&A (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)