Access Control¶

Aspected supports document-level access control through access keys. Each document in an index can be tagged with one or more access keys, and search queries can include an access filter to restrict results to only those documents that match at least one of the specified keys.

Not for direct end-user exposure

The access control system is not designed to be exposed directly to end users. Allowing users to set their own access filters would let them bypass restrictions by simply changing the filter values in their requests.

Instead, access control should be managed through an MCP (Model Context Protocol) server that sits between your end users and the Aspected instance. The MCP server is responsible for:

Authenticating the end user.
Resolving the correct access keys for the authenticated user.
Injecting the appropriate accessFilter into search requests before forwarding them to Aspected.

This ensures that users can only see documents they are authorised to access, without being able to tamper with the access filter.

Assigning Access Keys¶

When training an index, each row can include an optional accessList field — an array of string keys that control which filtered queries the document appears in:

{
  "rows": [
    {
      "id": "doc-1",
      "doc": { "title": "Public Report", "category": "finance" },
      "accessList": ["team-a", "team-b"]
    },
    {
      "id": "doc-2",
      "doc": { "title": "Confidential Memo", "category": "hr" },
      "accessList": ["team-c"]
    },
    {
      "id": "doc-3",
      "doc": { "title": "Open Document", "category": "general" }
    }
  ]
}

In this example:

doc-1 has keys team-a and team-b — it appears in filtered queries that include either key.
doc-2 has key team-c only.
doc-3 has no access keys — it is omitted from any filtered query unless explicitly included (see Including Documents with No Access Keys).

Filtering Search Results¶

Pass an accessFilter array in the search request to limit results to documents that have at least one matching access key.

Quick Filter Behaviour Overview

`accessFilter` value	Documents returned (from examples above)
(not set) or `null`	All documents (`doc-1`, `doc-2`, `doc-3`)
`["team-a"]`	`doc-1`
`["team-a", "team-c"]`	`doc-1`, `doc-2`
`["team-a", null]`	`doc-1`, `doc-3`
`[null]`	`doc-3`

Single Key¶

{
  "k": 10,
  "query": { "category": "finance" },
  "accessFilter": ["team-a"]
}

Only doc-1 is returned — it is the only document with the team-a key assigned.

Multiple Keys¶

Passing multiple keys returns documents that have any of the specified keys:

{
  "k": 10,
  "query": { "category": "finance" },
  "accessFilter": ["team-a", "team-c"]
}

Both doc-1 (which has team-a) and doc-2 (which has team-c) are returned.

Including Documents with No Access Keys¶

Documents without any access keys are excluded from filtered queries by default. To include them, add null to the access filter array:

{
  "k": 10,
  "query": { "category": "finance" },
  "accessFilter": ["team-a", null]
}

This returns documents that have the team-a key or have no access keys at all — in this case, doc-1 and doc-3.

Only Documents with No Access Keys¶

To return exclusively documents that have no access keys assigned, pass an array containing only null:

{
  "k": 10,
  "query": { "category": "finance" },
  "accessFilter": [null]
}

This returns only doc-3.

[null] vs null

Be careful not to confuse "accessFilter": [null] with "accessFilter": null. Setting the value to null rather than to an array containing null is the same as not providing the accessFilter at all, disabling filtering and returning all documents regardless of their access keys.