Authentication

Every partner route on the VIVIN API is called with a partner token that VIVIN issues for your platform.

Before you start

Item	Value
Who it is for	Booking platforms, booking engines and other partners that read listings or send bookings
Base URL	https://api.vivin.app, HTTPS only
Routes	Everything under your route prefix, for example /uniplaces-integration/… (see route prefixes)
Credential	A partner token. VIVIN issues it during onboarding: ask through Get help and support
Not for	Landlords scripting their own account (Management session) or AI clients (MCP OAuth)

The token identifies your platform, not one landlord. It reads the linked units of every VIVIN account that works with your platform (see Property and unit mapping). A single-landlord feed has its own prefix and its own token, tied to one account on VIVIN's side.

Credentials by route

Route	Send
Every route under your prefix	Authorization: Bearer <partner-token>
Any /uniplaces-integration/… route	The header above, or x-api-key: <webhook-key> with the webhook key VIVIN agreed with Uniplaces
POST /vivin-booking-engine-integration/property-listing	The header above and vivin-api-key: <account-key>, which picks the landlord account
/ical-integration/…	Nothing. The unit ID in the URL is the only secret (iCal feeds)

Send the partner token

Put the token in the Authorization header of every request.

GET /uniplaces-integration/listings HTTP/1.1
Host: api.vivin.app
Authorization: Bearer <partner-token>

curl https://api.vivin.app/uniplaces-integration/listings \
  -H "Authorization: Bearer <partner-token>"

• Write Bearer with a capital B, then exactly one space, then the token. bearer <partner-token> and two spaces are both rejected.
• Send the same header on every route under your prefix: the listing feeds, the full feeds, POST …/bookings and, if your platform has one, the inbound webhook. Use the token only under your own prefix.
• The token is a signed string. Treat it as opaque: do not decode it or build logic on its contents.

The x-api-key header (Uniplaces)

Uniplaces can authenticate with a webhook key instead of the partner token, on any Uniplaces route.

Header	Value
x-api-key	The webhook key VIVIN agreed with Uniplaces. Spaces around it are ignored
x-api_key	Accepted as another name for the same header

When the key matches, the request is accepted without an Authorization header. When it does not match, VIVIN checks Authorization as usual, so a wrong webhook key with no partner token returns 401 Missing integration credentials.

The vivin-api-key header (Vivin Booking Engine)

POST /vivin-booking-engine-integration/property-listing creates a property in one landlord account. The partner token alone does not say which, so the route also needs that account's key.

Header	Value
vivin-api-key	The landlord account's key. VIVIN sets it. The landlord sees only its last characters, as the read-only Integration API key on the Vivin Booking Engine card under Settings → Integrations → Booking Platforms

• Swagger's Authorize button sets only the partner token. Test this route with a client such as curl.
• On every booking-engine route, a vivin-api-key whose account now uses VIVIN's native booking engine returns 410 (Booking Engine API).

Test your token in Swagger

Each prefix has a live Swagger page at https://api.vivin.app/<prefix>, for example https://api.vivin.app/uniplaces-integration.

1. Open your platform's Swagger page.
2. Click Authorize.
3. Paste the token without the word Bearer. Swagger adds it; pasting Bearer <partner-token> sends the word twice and returns 401.
4. Click Authorize, then Close.
5. Expand GET /listings, click Try it out, then Execute.

A 200 means the token works. A 401 means it does not: see Errors.

Errors

An authentication failure on a partner route always returns 401, never 403, with the standard error body:

{
  "statusCode": 401,
  "message": "Missing integration credentials",
  "error": "UnauthorizedException"
}

Status	message	Cause	What to do
401	Missing integration credentials	No Authorization header (and, on Uniplaces routes, no matching x-api-key)	Add the header
401	Invalid integration credentials	The header is not Bearer <token>: wrong word or case, more than one space, or nothing after Bearer	Send exactly Bearer, one space, and the token
401	Unauthorized	The token is not valid here: a typo, a replaced token, or Bearer typed twice	Check the prefix and the token. If it still fails, ask VIVIN for a new token
401	Missing vivin-api-key header	POST /vivin-booking-engine-integration/property-listing without vivin-api-key, or with an empty one	Add the landlord account's key
401	Unauthorized	POST /vivin-booking-engine-integration/property-listing with a vivin-api-key that matches no account	Check the key with the landlord or VIVIN
503	This integration is not configured yet. Contact VIVIN support.	A single-landlord feed that VIVIN has not finished setting up. Your token is fine	Contact VIVIN. Retrying does not help

Other status codes are in Error handling.

Limits and retries

• Partner routes are not rate-limited, so they never return 429. How often to poll is covered in Keeping in sync.
• A 401 is final: retrying the same request returns the same 401. Fix the header first.
• VIVIN sets the token's lifetime when it issues it. If a token that worked starts returning 401 Unauthorized, ask VIVIN for a new one.

Keep the token safe

• Keep it on your server, in a secrets manager or server-side configuration. Never put it in a browser app, a mobile app or a public repository.
• Call the API over HTTPS only.
• If you think a token has leaked, contact VIVIN to replace it.
• The token opens only partner routes. The VIVIN app's own routes need a management session.

Troubleshooting

Symptom	Likely cause and fix
401 Unauthorized in Swagger, but curl works	Bearer was pasted into the Authorize dialog. Paste the token only
401 Invalid integration credentials from your HTTP client	The client lowercases Bearer or adds a second space. Build the header by hand
401 Missing integration credentials on the Uniplaces webhook	The x-api-key value does not match the agreed key, and no Authorization header was sent
401 Missing vivin-api-key header in Swagger	Swagger cannot send that header. Use curl
503 This integration is not configured yet…	The single-landlord feed is not live yet. Contact VIVIN

Related

• API reference: route prefixes and which API you need
• Error handling: the error body and every status code
• Listings and availability: your first call after authenticating
• Creating bookings: sending bookings to VIVIN
• Management session: scripting a landlord account