Public API endpoints

The endpoints on this page work without a session and without a widget key. They cover everything that happens before sign-in – creating an account, confirming the address, signing in, resetting a password, accepting an invitation – and what can be read from outside an account: service status, changelog, accessibility statement, enquiries, demos and the pickup of a cart by your shop. Widget endpoints are described in Widget endpoints, authentication for every other endpoint in API authentication.

Overview

Common rules

Every path starts with https://app.xicbot.de/api/v1/; the app calls them from that origin. Send JSON with Content-Type: application/json and Accept: application/json. Errors below /api/ are returned as JSON, unknown paths included. Field validation responds with 422, a text in message and, for each field, a list of messages in errors.

Rate limits

Requests are counted per origin: an IPv4 address on its own, an IPv6 address truncated to its /64 network. An IPv4 address in IPv6 notation such as ::ffff:192.0.2.10 counts as IPv4. The per-minute and per-hour limits are separate counters, and both must have room left. Endpoints with the same counter share it: status covers service status, changelog, demo lookup and accessibility together, auth-token covers confirmation and password reset, invitation covers both invitation endpoints. Once a limit is reached, the endpoint answers 429 with a Retry-After header in seconds.

Sign-in and password requests also keep counters of their own. Their 429 carries {"error": "too_many_attempts", "retry_in": …}, where retry_in gives the seconds until the next attempt is allowed. Limits for all other endpoints are listed in API limits.

Error responses

Calls from the browser

From a browser on another site, only the endpoints below /api/v1/public/ can be read, and only from the admitted origins; origins, methods, headers and the preflight lifetime are listed in API basics. Sign-up, sign-in, password and invitation endpoints are closed to other origins; cart pickup sets its own rules, as described further down.

Create an account

The address is normalised before it is stored: surrounding whitespace removed, Unicode normalisation form C, lower case, and without the suffix after a plus sign. For providers that ignore dots in the local part, the dots are removed as well. Where a provider serves the same mailbox under two domains, the address counts as the same under both. Anna+Test@example.com therefore becomes anna@example.com. A quoted local part is left unfolded. If the normalised address is already taken, including by a deleted account, the endpoint responds with 422 and {"error": "validation", "fields": {"email": ["validation.unique"]}}. In the app this step is called Create account, and the password rule reads At least 12 characters, including letters and digits.

Sign in

Second factor

1. 1

   Step 1

   Send the password

   If the account has a second factor and totp is missing, the endpoint responds with 428. error is totp_required when an authenticator app is set up, otherwise webauthn_required. The response also carries challenge, expires_in set to 600 seconds and methods, which lists the factors you can use in the second step: totp, webauthn or both. If the account only has security keys and sign-in with keys is not set up on the server, this step already returns 503 webauthn_unconfigured instead of 428. If an authenticator app is set up, you can send totp together with the password and skip the second step; on an account without an app, a code sent along yields bad_totp.

2. 2

   Step 2

   Prepare the security key

   If security keys are registered and sign-in with keys is set up on the server, the response contains a webauthn object with challenge, rp_id, allow (the permitted credential IDs) and timeout, which is at least 30. Use it to request confirmation on the key in the browser.

3. 3

   Step 3

   Send the proof

   Send email, challenge and either totp or webauthn, without the password and from the same IP address as in the first step. The challenge is valid for 600 seconds and is discarded on the fifth failed attempt; a wrong code, a rejected key and a request from a different IP address all count as failed attempts. Such a request gets 422 challenge_expired, but the challenge remains usable from the original address. Once it has expired or been used up, the endpoint also answers 422 challenge_expired, and you start again with the password.

The token is valid for 30 days; the exact time is in expires_at. It is named after the browser identification in User-Agent, at most 190 characters, or sitzung if none was sent. Every failed attempt counts against the counter for address and origin: wrong credentials, a wrong code, a rejected key, and an expired challenge or one sent from a different IP address. The counter for the origin alone counts only wrong credentials. A successful sign-in resets the counter for address and origin, but not the one for the origin alone. On a 429 the app shows Too many attempts. Please wait a moment., and for a blocked tenant This account is locked. Please write to mail@xicbot.de. Sessions and the second factor are covered in Sign-in and access and Account security.

Reset a password

The link points to https://app.xicbot.de/kennwort/neu?token=…&sprache=en and is valid for 60 minutes. Each newly sent link replaces the previous one. At most ten links per hour go out to the same mailbox, whatever network they are requested from; beyond that the response stays 200, but no email is sent, no new link is created and the last link sent remains valid. Only the two per-origin limits answer 429: the one for address and origin combined (3 per hour, counting every request whether or not the account exists) with too_many_attempts and retry_in, and the one for the origin alone (20 per hour) with a Retry-After header. In the app, the entry point and the button are labelled Forgot your password? and Request link.

Service status and changelog

Enquiry

Demo

What counts is the host of the address: lower case, without www. and without the scheme's default port. https://www.example.com/contact and https://example.com/ therefore lead to the same demo for example.com; a non-default port stays part of the host. If an active demo for this host is already running, you get it back with existing: true; nothing new is created and nothing counts against the daily limit. The demo widget is restricted to the host without its port.

Accessibility statement

Accept an invitation

An invitation from a team arrives as the link https://app.xicbot.de/einladung?token=…&sprache=en and is valid for 168 hours. The token has 48 characters; only its SHA-256 value is stored. How invitations are created and what each role may do is covered in Team and roles.

Pick up a cart

When the assistant puts a cart together during a conversation, the cart tool gives the visitor an address for your shop as next_url: the handover address configured there with ?token=… appended, or &token=… if the address already contains a query. Until then, the cart is held by XICBOT. The widget shows the link Continue, which opens next_url in a new tab. Your shop uses the token to read the cart and builds its own cart from it. If the assistant changes the open cart, the token stays the same; if it puts the cart together from scratch, a new cart with a new token is created. Setup is described in Catalog and shop and Tools.

The period is 7 days from the last change; whenever the assistant changes the cart during the conversation, it starts again. The response contains no ID of the tenant, the conversation or the handover and nothing about the visitor: holding the token gives access to the cart, not to the conversation.

curl https://app.xicbot.de/api/v1/cart/pickup/<token> \
  -H 'Accept: application/json'

Frequent questions