Authentication

Every authenticated request carries a Bearer API key. The key identifies the property you are acting on and the scopes you are allowed to use. There are no usernames, passwords, or OAuth flows — one key per integration.

The key format

A Veridien API key looks like this:

vrdn_live_xxxxxxxxxxxxxxxxxxxx

It is prefixed with vrdn_live_.
It is shown once, at creation. Veridien stores only a SHA-256 hash of the key — it can never be retrieved again, only revoked and replaced.
It is bound to one property. The property is implied by the key, so no endpoint asks you for a property id.

Treat keys like passwords

A key grants its scopes against your live property data. Keep it in a server-side secret store or environment variable, never in client-side code or a public repository. If a key leaks, revoke it immediately and issue a new one.

Creating a key

Create keys in the dashboard under Settings → API Keys:

Click Create key and give it a descriptive name (for example, Belena booking engine).
Select the scopes the integration needs — grant the minimum required.
Copy the key shown in the confirmation dialog and store it securely. It will not be shown again.

Keys can be revoked at any time from the same screen. A revoked key stops working immediately; requests using it then return 401.

Sending the key

Put the key in the Authorization header on every request:

curl https://veridien.app/api/v1/me \
  -H "Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx"

A successful call to /me confirms the key works and reports its property and scopes:

{
  "property_id": "p_8f2a1c",
  "scopes": ["availability:read", "reservations:write", "folio:write"],
  "request_id": "req_a1b2c3d4e5"
}

If the header is missing or malformed you get 401 missing_api_key; if the key is unknown, disabled, or expired you get 401 invalid_api_key.

Scopes

A key may only call an endpoint if it holds that endpoint's scope. Calling an endpoint without its scope returns 403 insufficient_scope. Scopes follow a resource:action shape.

Scope	Grants
`availability:read`	Read availability and rates (`/availability`, `/rates`, `/room-types`).
`rates:read`	Reserved for rate-only reads. The rate endpoints currently accept `availability:read`.
`reservations:read`	List and read reservations (`/reservations`, `/reservations/{id}`).
`reservations:write`	Create holds, confirm reservations, and cancel (`/holds`, `/holds/{id}/confirm`, `/reservations/{id}/cancel`).
`guests:read`	Read guest profiles, excluding PII.
`guests:read:pii`	Additionally return guest PII (email, phone, address, document).
`guests:write`	Register, link, and update guests (`POST /guests`, `PATCH /guests/{id}`).
`loyalty:read`	Read a guest's loyalty balance, tier, and ledger.
`loyalty:write`	Redeem loyalty points (`/loyalty/redemptions`).
`folio:read`	Read a reservation's folio.
`folio:write`	Post charges to a folio (`/reservations/{id}/folio/charges`).
`webhooks:manage`	Reserved for upcoming webhook subscription management.

Least privilege

Grant only the scopes an integration needs. A read-only availability widget needs just availability:read; a full booking engine typically needs availability:read, guests:write, reservations:write, and folio:write, plus loyalty:* if it surfaces points.

PII and guest data

Guest profiles split into a base view and a PII view. With guests:read you receive identifiers and non-sensitive fields (name, nationality, status, local-verification flag). To additionally receive email, phone, address, and document fields, the key must also hold guests:read:pii. This lets you build, say, a public-facing widget that reads guest status without ever exposing contact details.

Public endpoints

Two meta endpoints need no key and no scope:

GET /health — a liveness probe returning { "status": "ok" }.
GET /openapi.json — the OpenAPI 3.1 schema for the whole API.

Everything else requires a valid key with the appropriate scope.

Conventions — errors, idempotency, pagination, and rate limits.
Quickstart — a complete booking flow from key to confirmed reservation.