Managing Permissions & Groups

Learn how to set up permissions, create groups, and manage access to your Ensue memory network using the dashboard.

Overview

Ensue's permission system controls who can access what in your memory network. You can manage everything from the dashboard including creating groups, assigning members, and granting permissions to specific namespaces.

This guide walks through the dashboard experience. For CLI commands and technical details, see Access Control.

Understanding Permissions

Every permission grant combines three things: who gets access, what they can do, and where it applies.

The Six Actions

Action What it does
read View the contents of memory keys
create Add new memory keys
update Modify existing memory keys
delete Remove memory keys permanently
public_read Make matching keys discoverable without authentication

Most users need some combination of public_read, read, create, update, and delete. The sharing permission (manage users, groups, and permissions) is reserved for organization owners and cannot be granted via the share grant command.

Permission Scopes

Permissions can be applied at three levels:

Organization Level

Grants apply to everyone in the org, including all groups and individual users. Use this for broadly shared content.

Example: "Everyone in the org can read keys under announcements/"

Group Level

Grants apply to all members of a specific group. This most common way to manage permissions is to create a group, add users, and grant permissions to the group.

Example: "Members of the editors group can create and update keys under docs/"

User Level

Grants apply to a single user. Use this for individual namespaces or special access.

Example: "User alice has full access to keys under alice/"

Key Patterns

Permissions use key patterns to specify which memories they apply to. Patterns work like folder paths:

Pattern What it matches
(empty) All keys (full access)
project/ project/docs, project/config/settings, etc.
shared/docs/ shared/docs/readme, shared/docs/guide, etc.
alice/ alice/notes, alice/preferences, etc.

Use forward slashes to create namespaces, then grant permissions at the level that makes sense for your team.

Creating and Managing Groups

Creating a Group

In the dashboard:

  1. Navigate to the Groups section
  2. Click Create Group
  3. Enter a group name (e.g., editors, partners, read-only)
  4. Click Create

Adding Members to a Group

  1. Open the group you want to modify
  2. Click Add Member
  3. Select the user to add
  4. Click Confirm

Viewing Group Members

Open any group to see its current members and the permissions granted to that group.

Deleting a Group

  1. Open the group you want to delete
  2. Click Delete Group
  3. Confirm the deletion

Deleting a group removes all permission grants associated with it. Members lose any access they had through that group (though they keep access from other grants).

These patterns cover most common scenarios:

Group Permissions When to use
Admin public_read, read, create, update, delete on all keys Full access to all keys. User and permission management is reserved for org owners.
Editor public_read, read, create, update, delete on all keys 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 all keys Read-only access. Ideal for append only users that shouldn't be able to delete or modify any memories
Read Only public_read, read on all keys Read-only access. Ideal for consumers of shared knowledge who shouldn't modify it.

You can also create project-specific groups (e.g., project-acme-editors) with permissions scoped to a namespace like acme/.

Setting Up External Group Auto-Assignment

When external organizations join via an invite link, you can automatically assign their proxy user to a group. This means you configure access once, and every new external collaborator gets the right permissions immediately.

Configuring in the Dashboard

  1. Navigate to External Connections
  2. Find the External Group dropdown
  3. Select the group that external organizations should be assigned to
  4. Save your changes

For example, if you select the "partners" group and that group has read access to shared/, every new external org that joins will automatically be able to read your shared/ namespace.

Example: Sharing a Knowledge Base with Partners

Here's a complete walkthrough combining invites, groups, and permissions to share a knowledge base with partner organizations.

Step 1: Create a Group for Partners

Navigate to the Groups section in the dashboard, click Create Group, and name it partners.

Step 2: Grant Read Access to the Shared Namespace

Open the partners group and click Add Permission. Set the action to read and the key pattern to shared/. This gives every member of the group read access to your shared namespace.

Step 3: Set as External Group

Go to External Connections and select partners from the External Group dropdown. Save your changes. New external organizations will now be auto-assigned to this group.

Step 4: Generate an Invite Link

Go to API Keys & Users, click + Add External User, and generate a link. Share it with your partners.

Step 1: Create a Group for Partners

ensue share --command '{"command": "create_group", "group_name": "partners"}'

Step 2: Grant Read Access to the Shared Namespace

ensue share --command '{"command": "grant", "target": {"type": "group", "group_name": "partners"}, "action": "read", "key_pattern": "shared/"}'

Step 3: Set as External Group

ensue share --command '{"command": "set_external_group", "group_name": "partners"}'

Step 4: Generate an Invite Link

Go to API Keys & Users in the dashboard, click + Add External User, and generate a link. Share it with your partners. (Invite links are managed through the dashboard.)

Step 5: Partners Join and Get Access

When a partner org clicks the link and is approved (or auto-approved), they:

  1. Get a proxy user created in your org
  2. The proxy user is automatically added to the partners group
  3. They can immediately read all memories under your shared/ namespace using @your-org/shared/key-name

Next Steps