UserGroup access

Overview

UserGroup access applies policy-based access control to your users instead of to an API key. You attach policy sets to a UserGroup — a set of Zep users managed as one security subject — and every user in the group inherits its grants.

A UserGroup is a security grouping, not a data container. It is distinct from a user graph, which stores one user’s context, and from a standalone graph, which stores shared context. Grouping users for access control does not move or merge their data.

Today, UserGroup grants are enforced for Memory MCP standalone graph authorization: a connection in UserGroup ABAC mode decides which standalone graphs each authenticated Memory MCP user can discover, search, and write. Ordinary API-key traffic is governed by agent access instead, and is unaffected by UserGroup policies.

UserGroups

A project has two kinds of UserGroup:

• All Users — a virtual group that always contains every active user in the project, including users created later. It cannot be renamed, deleted, or have its membership edited. Every project has exactly one, even with zero users.
• Managed UserGroups — groups you create and name, with membership you administer explicitly. Use them to grant a subset of users access that All Users should not receive.

Members of a UserGroup are the same users you manage elsewhere in the project, referenced by their user UUID. Membership is direct — a UserGroup cannot contain another UserGroup — and is managed manually; Zep does not sync it from an identity provider. Deleting a user removes it from every group.

Effective UserGroups

Zep evaluates a user through their effective UserGroups: the virtual All Users group plus every managed UserGroup where the user has an active membership. Policy sets attached through more than one group are evaluated once.

Evaluation is default-deny. A user reaches a resource only when an enforced allow rule matches, and an enforced deny takes precedence over every allow across the combined set of groups. Membership changes, policy attachments, and policy edits apply to the next operation.

Attaching policies

You attach authorization policy sets to a managed UserGroup or to All Users. Retention policy sets cannot attach to a UserGroup.

To grant access to specific standalone graphs, a policy opts in to resource selectors with resource_selector_version: 1 and lists the graphs by their public uuid:

1
policy_set:
2
  name: support_graph_access
3
  description: Let the Support UserGroup search and add memory to one graph.
4
  mode: enforce
5
  spec:
6
    resource_selector_version: 1
7
    policies:
8
      - id: search_support_graph
9
        type: authorization
10
        effect: allow
11
        actions: [graph.search]
12
        resources:
13
          graph_uuids:
14
            - 2f6d9ff7-8f63-4d4d-a7f0-429eb75546d6
15
      - id: write_support_graph
16
        type: authorization
17
        effect: allow
18
        actions: [graph.add]
19
        resources:
20
          graph_uuids:
21
            - 2f6d9ff7-8f63-4d4d-a7f0-429eb75546d6

A rule without resources is action-wide and applies to every standalone graph, including graphs created later. The standalone graph authorization guide covers how these grants map to Memory MCP tools, directory filtering, attribute-filtered search, write gates, and migrating a connection to UserGroup ABAC.

Managing UserGroups

Project API keys can create, read, update, and delete managed UserGroups. They can also list and change membership. The account must have the ABAC entitlement. Use a default_allow project API key. A default_allow key includes project read and write permission. A default_deny key does not, and attached policies do not grant this surface.

• SDKs — use the user_group methods with a project API key to manage groups and membership. API keys cannot list, attach, or detach policy sets on a UserGroup.
• Dashboard — account administrators can use the Users & Groups section to manage groups, membership, and policy-set attachments.
• zepctl — the user-group commands manage groups, membership, and policy attachments, and the user-group and user dry-run commands report what a group or user would be allowed without changing any state. Create the policy set first, then attach it:

$
zepctl auth login
$
zepctl config set-project
$
$
# Create the policy set from the YAML above
$
zepctl policy-set validate --file policy.yaml
$
zepctl policy-set create   --file policy.yaml
$
$
# Groups, membership, and attachments
$
zepctl user-group list
$
zepctl user-group create --name Support --description "Support-facing users"
$
zepctl user-group members add <group-uuid> <user-uuid>
$
zepctl user-group policy-sets attach <group-uuid> <policy-set-uuid>
$
$
# Dry-run evaluation, with no state change
$
zepctl user-group evaluate <group-uuid> --action graph.search --graph <graph-uuid>
$
zepctl user evaluate <user-uuid> --action graph.search --graph <graph-uuid>

Policy-set authoring and the shared zepctl commands also appear under agent access.