Access Control

Control access to memories with fine-grained permissions for agents, teams, and organizations. Manage groups, grant scoped access, and configure external collaboration.

Overview

Ensue's access control system determines who can do what with your memories. Permissions are granted at three levels—organization, group, and user—and cascade downward.

┌──────────────────────────────────────────────────────────────┐
│  Organization                                                │
│  org-level grants apply to everyone                          │
│                                                              │
│  ┌──────────────────────────┐  ┌───────────────────────────┐ │
│  │  Group: editors          │  │  Group: viewers           │ │
│  │  group grants apply to   │  │  group grants apply to    │ │
│  │  all members             │  │  all members              │ │
│  │                          │  │                           │ │
│  │  ┌────────┐  ┌────────┐  │  │  ┌────────┐  ┌────────┐   │ │
│  │  │ alice  │  │  bob   │  │  │  │ carol  │  │  dan   │   │ │
│  │  │ (user) │  │ (user) │  │  │  │ (user) │  │ (user) │   │ │
│  │  └────────┘  └────────┘  │  │  └────────┘  └────────┘   │ │
│  └──────────────────────────┘  └───────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

A user's effective access is the union of all grants that apply to them: their direct user grants, the grants on any groups they belong to, and any org-level grants. There is no "deny" mechanism—permissions are purely additive.

The share tool requires the sharing permission, which is scoped to a namespace prefix—you can only grant permissions for keys within your allowed namespace.

Permission Actions

Five grantable actions control what operations a user can perform on matching keys, plus an org-owner permission:

Action Description
read Read the value of memory keys
create Create new memory keys
update Modify existing memory keys
delete Delete memory keys
public_read Makes matching memory keys discoverable without authentication. Use this to expose specific namespaces publicly.

The sharing permission (manage users, groups, and permissions via the share MCP tool) is reserved for organization owners and cannot be granted via the share grant command.

Permission Scopes

Scope Description Example
Organization Applies to all users in the org "Everyone in the org can read keys matching public/"
Group Applies to all members of a specific group "Members of the editors group can create and update keys matching docs/"
User Applies to a single user "User alice can read, create, update, and delete keys matching alice/"

Key Patterns

The key_pattern in commands is a namespace prefix that gets converted to a regex. Only alphanumeric characters, _, -, and / are allowed.

Key Pattern Matches
"" (empty) All keys (wildcard)
alice/ alice/docs, alice/notes/todo
team/ team/data, team/config/settings
shared/docs/ shared/docs/readme, shared/docs/guide

Managing Permissions

Grant Access

Grant permissions to a user, group, or organization:

# Grant read access to a user
ensue share --command '{"command": "grant", "target": {"type": "user", "username": "bob"}, "action": "read", "key_pattern": "project/"}'

# Grant update access to a group
ensue share --command '{"command": "grant", "target": {"type": "group", "group_name": "developers"}, "action": "update", "key_pattern": "code/"}'

# Grant access to entire organization
ensue share --command '{"command": "grant", "target": {"type": "org"}, "action": "read", "key_pattern": "public/"}'

# Make a namespace publicly discoverable
ensue share --command '{"command": "grant", "target": {"type": "org"}, "action": "public_read", "key_pattern": "public/"}'

Revoke Access

Remove previously granted access by grant ID:

ensue share --command '{"command": "revoke", "grant_id": "e516c156-1484-44f7-a47d-65176c0aba8b"}'

List Grants

View all grants, optionally filtered:

# List all grants
ensue share --command '{"command": "list"}'

# Filter by target type
ensue share --command '{"command": "list", "target_type": "group"}'

# Filter by action
ensue share --command '{"command": "list", "action": "update"}'

Groups

Groups let you manage permissions for multiple users at once. Any permission granted to a group automatically applies to all of its members.

Create and Delete Groups 

# Create a group
ensue share --command '{"command": "create_group", "group_name": "editors"}'

# Delete a group
ensue share --command '{"command": "delete_group", "group_name": "editors"}'

Add and Remove Members 

# Add a user to a group
ensue share --command '{"command": "add_member", "group_name": "editors", "username": "alice"}'

# Remove a user from a group
ensue share --command '{"command": "remove_member", "group_name": "editors", "username": "alice"}'

These group patterns cover most common access scenarios:

Group Suggested Permissions Use Case
Admin public_read, read, create, update, delete on .* Full access to all keys. User and permission management is reserved for org owners.
Editor public_read, read, create, update, and delete on .* Can read, write, and delete memories, but not manage users. Good for contributors who should be able to add and modify content.
Create public_read, read, create on .* Read-only access. Ideal for append only users that shouldn't be able to delete or modify any memories
Read Only public_read and read on .* Read-only access. Ideal for consumers of shared knowledge who shouldn't modify it.

External Collaboration

You can invite external organizations to collaborate on your memory network. When an external org joins, a proxy user is created in your organization that represents them. This proxy user is a regular user within your permission system, however, you can only manage the proxy users permissions by editing its group permissions that you set when you invited it.

Proxy users sit inside your org's permission hierarchy just like any other user:

┌───────────────────────────────────────────────────────────────┐
│  Your Organization                                            │
│                                                               │
│  ┌───────────────────────────┐  ┌───────────────────────────┐ │
│  │  Group: editors           │  │  Group: partners          │ │
│  │                           │  │                           │ │
│  │  ┌────────┐  ┌────────┐   │  │  ┌─────────────────────┐  │ │
│  │  │ alice  │  │  bob   │   │  │  │ proxy: bravo  │  │ │
│  │  │ (user) │  │ (user) │   │  │  │ (auto-created)      │  │ │
│  │  └────────┘  └────────┘   │  │  └─────────────────────┘  │ │
│  └───────────────────────────┘  └───────────────────────────┘ │
│                                                               │
│  Partner Org accesses your memories via @your-org/key         │
│  Their access is governed entirely by the proxy user's        │
│  permissions.                                                 │
└───────────────────────────────────────────────────────────────┘

The proxy user's access is determined by:

  • The groups it belongs to (e.g., a "partners" group with read on shared/)
  • Any org-level grants that apply to everyone

You can also configure an external group so that all new proxy users are automatically added to a designated group when they join, giving them immediate access without manual setup.

For full details on invite links, the join flow, membership management, and cross-org memory access, see Invites & Cross-Org.

Commands Reference

The share tool supports these sub-commands (all require sharing permission):

Command Description
create_user Create a new API user
delete_user Delete an API user
create_group Create a new group
delete_group Delete a group
add_member Add a user to a group
remove_member Remove a user from a group
grant Grant a permission (to org, group, or user)
revoke Revoke a permission by grant ID
list List permission grants (optionally filtered, or cross-org with org_name)
set_external_group Set which group external orgs auto-join
get_external_group View current external group assignment
clear_external_group Remove external group auto-assignment

Membership management (approve, reject, remove members, leave orgs) is handled by standalone Org & Invite tools, not share sub-commands.

For making memories publicly discoverable without authentication, grant the public_read action on a namespace and see the Public Access API.

Next Steps