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

VVVhy3 I started off attempting to start my workflow with a trigger and entities with s...

Tico | Voiceflow Assistant•6/25/25, 12:03 AM

You can absolutely gate parts of a Knowledge Base – just don’t try to do it with entities alone. The cleaner pattern is:

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**.
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.
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:```json "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.
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.

Ddistinguished-brown You can absolutely gate parts of a Knowledge Base – just don’t try to do it with...

ltd-scarletOP•6/25/25, 12:07 AM

How do I edit metadata of my documents?

VVVhy3 How do I edit metadata of my documents?

Tico | Voiceflow Assistant•6/25/25, 12:08 AM

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

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

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

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

metadata

field to the multipart/form-data or JSON upload payload.
• Use metadata later when querying (

/knowledge-base/query

/knowledge-base/query

) with the

filter.metadata

filter.metadata

expression to quickly narrow results.

Docs → https://developer.voiceflow.com/reference/patch_v1-knowledge-base-docs-documentid

ltd-scarletOP•6/25/25, 1:19 AM

@majinnboo sorry for pinging, I saw that you were helping others - hopefully this might be something you could guide me on?

ltd-scarletOP•6/25/25, 1:19 AM

again, I hope I'm not a bother, I'd appreciate any help

Ddistinguished-brown You can update (or add) metadata on any *file* or *URL* document in your Knowled...

ltd-scarletOP•6/25/25, 6:13 AM

Am I able to edit Metadata for my original purpose after I've made the document?

Steve B. | IntelleSync.uk•6/25/25, 9:32 AM

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

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

ltd-scarletOP•6/25/25, 9:42 AM

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

ltd-scarletOP•6/25/25, 9:43 AM

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

ltd-scarletOP•6/25/25, 9:43 AM

in terms of api, it seems as if I should be using curl or postman to edit metadata as the AI suggested

ltd-scarletOP•6/25/25, 9:43 AM

Is there no way to do it via the website?

ltd-scarletOP•6/25/25, 9:43 AM

To edit metadata via the website

Steve B. | IntelleSync.uk•6/25/25, 9:51 AM

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…

Sskinny-azure The reason i ask is because what your trying to do is relatively advanced. I su...

ltd-scarletOP•6/25/25, 9:54 AM

This is perfect, thank you

ltd-scarletOP•6/25/25, 9:54 AM

The bot gave me this link but it didn't work, it must've typo'd

Sskinny-azure The reason i ask is because what your trying to do is relatively advanced. I su...

ltd-scarletOP•6/25/25, 9:55 AM

Are you experienced with curl? Should I get accomodated with using Postman instead of just curl?

Steve B. | IntelleSync.uk•6/25/25, 10:07 AM

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.

Sskinny-azure The reason i ask is because what your trying to do is relatively advanced. I su...

sacred-rose•6/25/25, 5:26 PM

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

sacred-rose•6/25/25, 5:27 PM

e.g. in here

sacred-rose•6/25/25, 5:29 PM

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:

�𝓐𝓼𝓱 this is great, follow up question, is there a way to make this work in an agent ...

Steve B. | IntelleSync.uk•6/25/25, 5:46 PM

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

sacred-rose•6/25/25, 5:52 PM

:/ shame, perhaps could be a future feature

sacred-rose•6/25/25, 5:53 PM

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.uk•6/25/25, 5:54 PM

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.

Steve B. | IntelleSync.uk•6/25/25, 5:54 PM

Yes, but Kb search won’t work you have to use the API.

sacred-rose•6/25/25, 5:55 PM

gotcha, thanks for the help

VVVhy3 @majinnboo sorry for pinging, I saw that you were helping others - hopefully thi...

majinnboo•6/25/25, 6:14 PM

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!

Sstatic-pink Hi just saw the ping! You can add metadata via the docs. And make updates to met...

ltd-scarletOP•6/25/25, 7:26 PM

I'd love some pictures if you would please, where's the api reference tab specifically?

Ssacred-rose :/ shame, perhaps could be a future feature

ltd-scarletOP•6/25/25, 10:33 PM

I created my access control successfully with prompts and warnings on portions of the knowledge base

ltd-scarletOP•6/25/25, 10:33 PM

it's slightly less secure but for most use cases this works out perfect

ltd-scarletOP•6/25/25, 10:33 PM

especially for mine

ltd-scarletOP•6/25/25, 10:33 PM

if you'd want help on setting it up I can help

VVVhy3 I'd love some pictures if you would please, where's the api reference tab specif...

majinnboo•6/26/25, 3:40 AM

right here

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