Authentication

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

The key format

A Veridien API key starts with vrdn_live_, followed by 40 letters and digits. This reference writes it as YOUR_API_KEY.

It is shown once, when you create it. Veridien stores only a SHA-256 hash of the key, so it can never be shown again, only revoked and replaced.
It is bound to one property. The property comes from the key, so no endpoint asks you for a property id.
It can carry an expiry date. Without one, it never expires.

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 at once and create a new one.

Creating a key

You create keys in the dashboard under Settings → API keys. You need the permission to manage API keys.

Click Create key and give the key a name you will recognise (for example, Sunrise Bay website).
Choose the scopes the integration needs, and only those.
Optionally set an expiry date. Requests are rejected from the end of that day.
Copy the key from the confirmation dialog and store it securely. It is not shown again.

You can revoke a key at any time from the same screen. A revoked key stops working at once, and requests that use it 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 YOUR_API_KEY"

If the header is missing or malformed you get 401 missing_api_key. If the key is unknown, revoked, or expired you get 401 invalid_api_key. You also get 401 invalid_api_key while the property is not yet verified, is suspended, or does not have the API module on its plan.

Check your key

GET /me

Scope: none. Any valid key may call it.

Returns the property the key is bound to and the scopes it holds. Call it first to confirm a key works.

{
  "property_id": "4e1b7c2a-9d3f-4a6e-8b5c-0f2d7a9e3c18",
  "property_slug": "sunrise-bay",
  "scopes": ["availability:read", "reservations:write", "folio:write"],
  "request_id": "req_0b9d3e6a-2f4c-4a1e-9c7b-5d8f1a3e6b20"
}

Field	Type	Notes
`property_id`	string	The property's id (a UUID).
`property_slug`	string	The property's URL slug.
`scopes`	array	The scopes this key holds.
`request_id`	string	This request's id.

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 the property and catalog: `/property`, `/room-types`, `/availability`, `/rates`, `/services`, `GET /rate-plans`, and `POST /promo-codes/validate`.
`rates:read`	Read rate-management resources: `GET /rate-plans/{id}/intervals`, `/inclusions`, and `/promo-codes`.
`rates:write`	Create, update, and delete rate plans and promotions, seasonal intervals, inclusions and credits, and promo codes.
`reservations:read`	List and read reservations (`/reservations`, `/reservations/{id}`).
`reservations:write`	Create holds, confirm them, and cancel reservations (`/holds`, `/holds/{id}/confirm`, `/reservations/{id}/cancel`).
`guests:read`	Read guest profiles, without personal data.
`guests:read:pii`	Also return guest personal data (email, phone, date of birth, ID 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 webhook subscription management. No endpoint uses it yet.

Least privilege

Grant only the scopes an integration needs. A read-only availability display needs just availability:read. A full booking flow typically needs availability:read, guests:write, reservations:write, and folio:write, plus the loyalty scopes if it shows points.

PII and guest data

Guest profiles come in a base view and a personal-data view. With guests:read you receive ids and non-sensitive fields (name, nationality, the local-verification flag). To also receive email, phone, date_of_birth, id_type, and id_number, the key must also hold guests:read:pii. That lets you build, say, a widget that reads a guest's name without ever exposing contact details.

Public endpoints

Two meta endpoints need no key and no scope:

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

Everything else needs a valid key with the right scope.

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