Authentication
Public endpoints are open. Everything else is authenticated with a personal API key sent in the X-Api-Key header.
Public endpoints need no key
Endpoints under /api/public return what any visitor of your Loupe site can see: published events, rooms, pages, maps, footfall and the catalogue. Call them without any credentials.
Sending a staff key to a public endpoint changes the result: collections then also include your organization's unpublished items, as they appear in the admin. Leave the key out when you mirror what visitors see.
API keys
Integrations authenticate with an API key. A key acts as the person who created it: it carries that person's role, permissions and organization. There are no separate scopes and keys do not expire; they stay valid until they are revoked or their owner is deactivated.
Create a key
- In the Loupe admin, open Settings → API.
- Choose New API key, give it a label that says where it will be used (for example
Website agenda sync), then Create API key. - Copy the token. It is shown once: Loupe only stores a hash of it, so a lost key cannot be recovered, only replaced.
Creating keys requires the api_keys.manage permission. The Administrator role has it; other roles need a custom role that grants it.
A key is 64 lowercase hexadecimal characters, with no prefix:
4f1c9e0b7a2d…c83e # 64 characters in totalSend the key
Pass the key in the X-Api-Key header:
curl https://api.loupe.ch/api/manager/reservations?organization=riveville \ -H "X-Api-Key: $LOUPE_API_KEY" \ -H "Accept: application/json"Only the header is accepted. A key placed in the URL is ignored, because URLs end up in logs, browser history and analytics.
Use a dedicated account
Because a key inherits everything its owner can do, create integrations from a dedicated staff account with a custom role that grants only the permissions the integration needs (for example, reading reservations). If the integration leaks, revoke that one key without touching anyone's personal access.
Keep keys on the server
Never ship a key in browser code or a mobile app: anyone could read it. Browsers cannot send the X-Api-Key header to Loupe from another domain anyway, so call authenticated endpoints from your server, and only call public endpoints from the browser.
Manage keys over the API
The same endpoints power the admin screen. They act on the keys of the authenticated person.
| Method | Path | Result |
|---|---|---|
GET | /api/authentication/api-keys | Your keys: id, label, createdAt, lastUsedAt, revokedAt |
POST | /api/authentication/api-keys | Creates a key from {"label": "…"} and returns its token, once. The label is required, 1 to 180 characters, otherwise 422 |
DELETE | /api/authentication/api-keys/{id} | Revokes the key; returns 204 |
lastUsedAt tells you whether a key is still in use before you revoke it. The admin screen shows the same information under Last used. Revocation takes effect on the next request.
When authentication fails
| Situation | Response |
|---|---|
| Missing, unknown or revoked key on a protected endpoint | 401 Unauthorized |
| Valid key, but the owner lacks the permission | 403 Forbidden |
| Owner deactivated, or organization disabled | 401 Unauthorized |
| Invalid key on a public endpoint | Handled as an anonymous request |
Other credentials
The Loupe apps sign in people with a session cookie set by /api/authentication/login. It is meant for people in a browser, not for integrations. Assistants connected through MCP use OAuth tokens that only work on the MCP endpoint. For scripts and integrations, use an API key.