national-gold•3mo ago

Knowledge Base Access Control - How to

I started off attempting to start my workflow with a trigger and entities with specific PINs written in the entities to "allow access" to a certain portion of the knowledge base that the AI Agent has access to Is there another way I should be going about this? For clarity, this is to control who has access to what information that the AI Agent has access to in their knowledge base - using a PIN number as access control

19 Replies

Tico | Voiceflow Assistant•3mo ago

You can absolutely gate parts of a Knowledge Base – just don’t try to do it with entities alone. The cleaner pattern is: 1. Tag or add metadata to the documents you want to protect
• Example: all docs that only “PIN 1234” users may see get the tag pin_1234.
• You can attach tags when you upload the file or afterwards with the Tags API. 2. Ask the user for their PIN once at the start of the flow
• Capture it in a variable (say user_pin).
• Validate it with an If/Choice step or a quick Code step, then map it to the tag you’ll allow (e.g. set allowed_tag = "pin_" + user_pin). You can also fall back to a “no-access” path if the PIN isn’t recognised. 3. Filter every KB search with that tag
• KB Search step → right panel → Filters › Tags › Include → choose a variable and point it to allowed_tag.
• If you drive searches through the KB Query API instead, add:

      "filters": {
        "metadata.tags": { "$in": [ "{{allowed_tag}}" ] }
      }

      "filters": {
        "metadata.tags": { "$in": [ "{{allowed_tag}}" ] }
      }

Now the agent will only retrieve chunks that carry that tag, so users without the proper PIN never see the protected content. 4. Optional – multiple access levels
• If a PIN should unlock several groups, store the list in an array variable (e.g. ["pin_1234","general"]) and use $in on that array.
• You can also keep completely separate KBs and swap Project ID / Assistant ID via the Dialog Manager API, but tag-filtering is usually simpler. Key docs • KB Search step: docs.voiceflow.com → “KB Search Step”
• Filtering & metadata guide (JSON examples): https://developer.voiceflow.com/docs/filter-with-metadata
• Tags API reference: https://developer.voiceflow.com/v2.0/reference/post_v3alpha-knowledge-base-tags With this pattern you keep one assistant, one KB, and enforce access control purely in the query layer – no need to juggle multiple projects or complicated entity logic.

national-goldOP•3mo ago

How do I edit metadata of my documents?

Tico | Voiceflow Assistant•3mo ago

You can update (or add) metadata on any file or URL document in your Knowledge Base with a single PATCH call to the Management API. 🔧 Endpoint

PATCH  https://api.voiceflow.com/v1/knowledge-base/docs/{documentID}

PATCH  https://api.voiceflow.com/v1/knowledge-base/docs/{documentID}

• {documentID} – the ID you receive when the document is first uploaded or when you list your docs. 🔐 Headers

Authorization:  DM_API_KEY            # found in your project → Integrations tab
Content-Type:  application/json

Authorization:  DM_API_KEY            # found in your project → Integrations tab
Content-Type:  application/json

📦 Request body

{
  "data": {
    "metadata": {
      "department": "support",
      "version":    3,
      "public":      true
    }
  }
}

{
  "data": {
    "metadata": {
      "department": "support",
      "version":    3,
      "public":      true
    }
  }
}

– The object you pass in metadata can contain nested objects, arrays, numbers, strings or booleans (≤ 10 KB total). – The call applies the new metadata to all chunks of that document. – This operation is not available for documents of type table; for tables you need to re-upload the row(s) with the desired metadata. 📄 Successful response (200)

{
  "data": {
    "status": "SUCCESS",
    "documentID": "doc_123",
    "metadata": {
      "department": "support",
      "version": 3,
      "public": true
    },
    "updatedAt": "2025-06-25T01:45:12.123Z"
  }
}

{
  "data": {
    "status": "SUCCESS",
    "documentID": "doc_123",
    "metadata": {
      "department": "support",
      "version": 3,
      "public": true
    },
    "updatedAt": "2025-06-25T01:45:12.123Z"
  }
}

Tips • If you only need to add one new key, you still pass the full metadata object; keys you don’t include are preserved. • When you first upload a document (file or URL) you can attach metadata immediately by adding the same metadata field to the multipart/form-data or JSON upload payload. • Use metadata later when querying (/knowledge-base/query) with the filter.metadata expression to quickly narrow results. Docs → https://developer.voiceflow.com/reference/patch_v1-knowledge-base-docs-documentid

national-goldOP•3mo ago

@majinnboo sorry for pinging, I saw that you were helping others - hopefully this might be something you could guide me on? again, I hope I'm not a bother, I'd appreciate any help Am I able to edit Metadata for my original purpose after I've made the document?

Steve B. | IntelleSync.ai•3mo ago

@VVhy3 How experienced are you with Voiceflow and the knowledgebase API?

national-goldOP•3mo ago

Started voiceflow about yesterday but I've already gotten accomodated to the knowledge base and the prompt system with triggers and some ideas of how entities work I've pretty much already done what I mentioned in this forum but using the prompts solely which isn't as secure as it should be in terms of api, it seems as if I should be using curl or postman to edit metadata as the AI suggested Is there no way to do it via the website? To edit metadata via the website

Steve B. | IntelleSync.ai•3mo ago

The reason i ask is because what your trying to do is relatively advanced. I suggest you first understand how to upload documents to your KB with metadata via api, then you'll need to understand how to filter your results using operators. You will also need to understand how to classify the users question using AI in order to make the operators work.
You. can learn about uploading with metadata and operators here: https://docs.voiceflow.com/reference/filter-with-metadata

Voiceflow

Filtering with Metadata

Advanced Query Filtering Our new query filtering capabilities enable users to perform precise searches within their data using a robust set of operators. You can apply various filters to your data, such as: Equality and Comparison: $eq, $ne, $gt, $gte, $lt, $lte Array Operations: $in, $nin, $all Lo…

national-goldOP•3mo ago

This is perfect, thank you The bot gave me this link but it didn't work, it must've typo'd Are you experienced with curl? Should I get accomodated with using Postman instead of just curl?

Steve B. | IntelleSync.ai•3mo ago

Yes, i would learn how to take the curl command and use it in an API like Postman or even in Voiceflows own API step in the canvas which is what I mainly use. You can even use the voiceflow docs to implement your API calls.

adverse-sapphire•3mo ago

this is great, follow up question, is there a way to make this work in an agent step? e.g. in LLM Description on the Knowledge Base area of an agent step if i put something like "look for files tagged 'category_sheet' first, followed by files tagged 'product_sheet'", would that work? as where we'd want the info it'd be in an agent step. @Tico | Voiceflow Assistant

adverse-sapphire•3mo ago

e.g. in here

adverse-sapphire•3mo ago

as i see in this it needs the KB Search step, but not sure how/if would work for an agent step • KB Search step → right panel → Filters › Tags › Include → choose a variable and point it to allowed_tag. • If you drive searches through the KB Query API instead, add:

Steve B. | IntelleSync.ai•3mo ago

This won’t work as you need to make an API call to the KB with the operators in the body.

adverse-sapphire•3mo ago

:/ shame, perhaps could be a future feature i suppose a workaround could be have a path that gets triggered when kb search is needed, have it exit, perform search, then go back into agent step?

Steve B. | IntelleSync.ai•3mo ago

You could still do with the agent step if you use the api tooling and call on the KB or even by a path that way just not through prompting. Yes, but Kb search won’t work you have to use the API.

adverse-sapphire•3mo ago

gotcha, thanks for the help

majinnboo•3mo ago

Hi just saw the ping! You can add metadata via the docs. And make updates to metadata as well. The docs allow you to ask a question to your knowledge base with your specific tags and then it gives you the code you need to put into your voiceflow api blocks on the canvas to get the filtered results. It's really cool and imo the best documentation on the market right now. To get to the knowledge base api you click on the docs from the voiceflow homepage. Then you click on the API reference tab, then on the side is the knowledge base API. Let me know if you need some pictures or anything else to help!

national-goldOP•3mo ago

I'd love some pictures if you would please, where's the api reference tab specifically? I created my access control successfully with prompts and warnings on portions of the knowledge base it's slightly less secure but for most use cases this works out perfect especially for mine if you'd want help on setting it up I can help

majinnboo•3mo ago

right here

Knowledge Base Access Control - How to

Did you find this page helpful?