Knowledge from a portal behind a login

An assistant reads your public site through a sitemap. A portal behind a login has no sitemap that we are allowed to read. Still, you want the assistant to know the help texts there: how to download an invoice, where to change a setting. There are two ways to do that. Both work without us needing a user's session, and your portal keeps deciding for itself what goes out.

This is a guide for whoever builds the portal. A developer can follow it without us. You create the assistant itself first, see Support Studio.

Feed or push

Choose a feed if the portal can show a list. Choose a push if the portal itself knows when something changes. You can use both. Each way has its own source, and a path that appears in both is then in there twice.

The format

A feed returns JSON, and a push sends the same under items.

{
  "versie": 1,
  "items": [
    {
      "pad": "/help/facturen",
      "url": "https://portal.voorbeeld.nl/help/facturen",
      "titel": "Facturen downloaden",
      "tekst": "Open Facturatie en kies Downloaden naast de maand ...",
      "categorie": "Facturatie",
      "bijgewerkt": "2026-10-06T10:00:00Z"
    }
  ]
}

A bare list ([ {...} ]) is also allowed. The English field names title, text, category and updated are read as well.

Limits

• At most 2 MB per response or push and at most 500 items. With a feed the rest is ignored, a push with more is rejected.
• An item that is not valid is rejected with a fixed reason (pad-ongeldig, titel-leeg, tekst-leeg, url-andere-oorsprong, dubbel). The rest carries on as normal.
• A feed must be https. A feed with a key never goes over plain http.
• If a feed returns nothing or nonsense, the existing knowledge stays. A portal that is briefly down doesn't wipe the assistant.

Setting up a feed

1. Go to Support, Knowledge, Portal behind a login and enter the https address of the feed. You get a key (dpf_...). It is shown on screen once; in the database it is stored encrypted. Copy it right away.
2. Put the key in your portal. The portal only responds if the header Authorization: Bearer dpf_... is correct, and otherwise returns a 401 without explanation.
3. Choose Read again now. After that Denkploeg reads the feed every night.
4. You create a new key with Rotate key. The old one then stops working, so put the new one into your portal right away. Until that is done, the source shows an error and the knowledge stays.

A source shows its status: waiting for the first read, read, or an error with the reason (the feed refused the key, was too large, did not return JSON or no valid items).

Setting up a push

1. An owner of the agency creates a key under Agency, Connection keys with the right Send knowledge to an assistant. That checkbox is not on by default. The key (dpb_...) is shown on screen once.
2. Under Support, Knowledge, at "Or let the portal send it itself" there is an example with the ID of your assistant in it, and what your portal last sent.
3. Your portal sends:

POST /api/bureau/support/kennis
Authorization: Bearer dpb_...

{
  "assistent": "<id van de assistent>",
  "items": [ { "pad": "/help/facturen", "titel": "...", "tekst": "..." } ],
  "verwijder": ["/help/oud"],
  "volledig": false
}

• A push works on pad: an unchanged item stays, a changed item is replaced.
• verwijder removes paths (at most 500).
• With volledig: true, items is the complete list, and everything that isn't in it disappears. An empty list with volledig is rejected: that would wipe everything.
• On success: {"ok":true,"aangepast":2,"ongewijzigd":10,"verwijderd":1,"geweigerd":[]}.

Error codes: 401 sleutel-ongeldig, 403 recht-ontbreekt, 404 niet-gevonden (also for an assistant of another agency), 400 ongeldige-vraag, 413 te-groot or te-veel-items, 429 te-druk (at most 30 pushes per minute per key).

The key can only write knowledge into the push source of that one assistant, and nothing else. Every push is in the agency's audit trail.

Sending the open page along

If the assistant itself sits in this portal, the script sends the path, the title and the main headings (h1 and h2) along with the question on every page change. Only those fields: no query, no text from forms. That way "how does this screen work" is about the screen the visitor is on. If your feed or push has an item with exactly this path, that item comes first in the knowledge.

So make sure every screen has a clear <title> and an <h1>, and that the pad of an item equals the path of that screen.

Privacy and security

• Don't put anything personal in it. Everything in an item is something the assistant can tell any visitor. These are help texts for everyone who uses the portal, not data of a user. You recognise a signed-in user through Linking Support, and that is handled separately.
• Text from outside. Text from a feed is just as untrusted as site text. It goes into the assistant wrapped, and can only come back as text in a chat. There is no tool that changes anything. A source link can only point to its own origin.
• The key lives only in your portal's environment, not in the repo or the logs. With a feed the key never goes along on a redirect to another origin.
• Our fetching refuses internal addresses, has a time budget and a limit on size, and only reads JSON.

Done when

• The feed gives 200 and JSON in this format with the right key, and 401 without one or with a wrong key (or the push gives ok: true).
• Every screen that needs help has an item with the path of that screen.
• There is nothing in it that isn't meant for every user.