API Reference

Interfaces for developers: public endpoints, chat widget, sign-in and the REST API with API keys.

This API reference describes the Zentor App interfaces you can call from your own websites and applications: public endpoints for forms, the product configurator and content, the chat widget, the demo chatbot, and sign-in including single sign-on. Each endpoint page lists the method, path, authentication, parameters, an example request and response, and the documented error codes.

Authentication: the endpoints for forms, the product configurator and content can be called without signing in. The chat widget endpoints expect your widget's embed token in the `X-Widget-Token` header and only accept calls from the domains approved for that widget. The sign-in endpoints issue an access token (JWT) and a refresh token for user sessions.

API access with API keys: for your own applications and server-to-server integrations, the REST API is available at the base URL `https://zentor-app.de/api/v1`. Zentor enables API access for your account on request. Administrators then create their own keys in the dashboard under “API keys” and define their permissions (scopes) – for appointments and bookings, chatbot, communication, files, knowledge base, reports and web data. Each area has a read scope (`<area>.read`, GET only) and a write scope (`<area>.write`, which includes read access), for example `appointments.read` or `knowledge.write`. Send the key in the `Authorization: Bearer <API key>` header or, alternatively, in the `X-API-Key` header. Use `GET /api/v1/me` to check which account and scopes a key belongs to.

The full key is shown only once, when it is created. Store it securely and on the server side only – never in browser code or mobile apps. Keys can be given an expiry date, rotated and revoked. The REST API only exposes functions included in your package, and all data is restricted to your account. Typical errors: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` or `API_KEY_REVOKED` (key missing, wrong, expired or revoked), 403 `API_ACCESS_NOT_ENABLED` (API access not enabled for the account), 403 `API_SCOPE_MISSING` (the key lacks the required scope), 403 `TENANT_NOT_ACTIVE` or `TENANT_LOCKED` (account inactive or locked) and 404 `API_ENDPOINT_NOT_AVAILABLE` (the endpoint is not available through the REST API).

Responses and limits: all endpoints respond with JSON. A successful response has a 2xx status and `"ok": true`; an error response contains a machine-readable error code (in the `error` or `error.code` field) and a message. Each IP address can make 2,000 requests within 15 minutes; stricter limits apply to form, verification and sign-in endpoints and are stated on the respective page. When a limit is exceeded, the server responds with 429 `RATE_LIMIT_EXCEEDED`. Endpoints marked as not idempotent should not be retried automatically after a connection failure, as this can create duplicate requests or messages.

Send passwords, tokens, API keys and verification codes only in the request body or in headers over HTTPS – never in URLs, logs or support requests.

Authentication (5)Sign-in, token refresh, password reset, SSO completion – and API access with API keys.Public Forms (11)Contact, consultation request, access request, payment and account activation.Product Configurator (5)Package catalog, price preview, email confirmation and configuration submission.Public Content (6)Legal texts, marketing pages, website theme and text colours.Chat Widget (9)All endpoints used by the chat widget embedded on your website.Demo Chatbot and SSO (13)The public demo chatbot and the single sign-on endpoints (SAML/OIDC).
← Back to overview