Authentication

The Public API authenticates with API keys that an operator generates in the Foyer app.

Generate a key under Settings → API keys. The key is shown once, at creation time, and stored only as a hash — if you lose it, rotate it rather than trying to recover it.

curl --request GET \
  --url https://getfoyer.app/api/v1/developer/stays \
  --header 'Authorization: Bearer fk_live_<your-key>'

Scopes

A key carries a scope of either full or read_only. A read_only key can only call read-only operations; the check is enforced server-side, not in the client.

Roles and modules

A key also carries a role — owner, staff, reception, housekeeping or maintenance — and an optional module override, mirroring the permissions an operator user has. Keys created before this system existed default to owner and keep full access.

Expiry

A key can be created with no expiry or with one of 30, 90 or 365 days. Expired keys are rejected for both the REST API and MCP.