Skip to Content
Baseera Docs
Knowledge

Knowledge access

Decide which users can find, cite and open each source, using tenants and access rules.

By default, anyone who can talk to an agent can get answers from every source in the knowledge bases attached to it. Two controls narrow that: tenants (whose documents a source is) and access rules (which readers may see it). A third, Users can open the original, controls whether people can open the file behind a citation.

Understand the three layers

LayerQuestion it answersWhere you set it
Tenant scopeWhose document is this?Where the source comes from: console, API, tenant upload
Access rulesWhich readers may find it?Who can read on a source or website, or access on a pushed item
Original fileMay a reader open the file behind a citation?Users can open the original per source

Tenants

A tenant is one of your customers. Your server puts a tenant id in the signed user token, and the runtime uses that id for every session. A browser or a chat message cannot choose it.

  • A source with no tenant is Platform-wide. It is searched for every tenant.
  • A source with a tenant belongs to that tenant only. Its users get answers from it. Other tenants never do.

The By tenant table on a knowledge base shows sources and chunks per tenant, with how many are ready, processing or failed. Use Show to filter the Sources table.

A user whose token has no tenant sees only platform-wide knowledge.

Let tenants add their own documents

Turn on Let tenants add their own documents on the agent's Knowledge page (default off), then Save to the draft and publish. An admin of one of your tenants can then upload documents with the upload component in your app. Only that tenant's users get answers from them. Your server authorizes each upload with a signed, short-lived token, so the browser cannot pick another tenant. Tenants manage only the documents they uploaded. They cannot see or delete platform-wide documents or documents you pushed.

Restrict a source with access rules

Rules compare what you put in the user token with what you write on the source. Leave the rules empty and everyone who can reach the knowledge can find the source.

On the knowledge base, press Access on the source. The dialog is titled "Who can read" followed by the source name. For a website, use Who can read its pages. For new uploads, open Who can read the files you add.

Write one rule per line in the form name: value, value. For example:

roles: staff, manager
region: sa, ae

Press Save.

A user qualifies when, for every line, their token has one of the listed values. Roles come from the token's role, other names from its claims. Matching is exact, and case matters. A user without the claim never sees the source, and nothing tells them it exists: it is left out of search, citations and links.

Limits: at most 10 rules and 2 KB in all, names of letters, digits, underscore, dot and dash up to 64 characters, and 1 to 20 values of up to 100 characters each.

The Who can read column of the knowledge table shows Everyone or Restricted. A rule the system cannot read shows Unreadable rules: nobody can read it, because the safe default for a broken rule is to show nothing.

Claims come only from the signed user token your server creates. See the user tokens reference.

Tightening and loosening

A stricter rule applies at once, even while a new version of the file is processing. A wider rule applies when the new version is ready, so a version is never exposed under rules it was not published with. The knowledge table shows "A new version is processing. A stricter rule applies now; a wider one applies when that version is ready."

A page from a crawled website follows its website's rules. Change them on the website, not on a single page.

Check it before users do

Use Test retrieval on the knowledge base. Under Search as a reader with these claims, type for example roles: staff to search as staff, and leave it empty to search as a reader with no claims. Only you see this. Users never choose their own claims.

Let users open the original

Citations show as chips with a title and a section or page. To let a user open the original file from a chip, turn on Users can open the original for that source. Otherwise the source is Private and the user sees only its title and section.

  • A link works for 5 minutes and is checked again when it is opened, so switching a source off stops older links working.
  • A link opens only if the source is cited in that user's own answer and the user qualifies for it now.
  • Crawled web pages open the live page instead.

What can go wrong

MessageCause and fix
"Write each rule as name: value, value."A line is missing the colon.
"A name uses letters, digits, underscore, dot and dash, up to 64 characters."Rename the claim.
"Each rule needs 1 to 20 values of up to 100 characters."Shorten or split the list.
"At most 10 rules and 2 KB in all."Combine rules.
"A page follows its website's rules. Change them on the website."Edit the website, not the page.
"You can't change who reads this."Your role cannot change access. Ask an owner, admin or developer.
A user says they cannot see a document you expectedCheck their token has the claim, spelled and cased exactly, and that their tenant matches. Reproduce it with Test retrieval.

Text already shown to a user stays in their session history after you tighten a rule. Only new answers and links change.

Next steps

On this page