Roles & Permissions
Granular, role-based access control for your organization. Roles determine what each team member can see and do in the MemorySync dashboard and API. Every organization starts with five built-in system roles, and Enterprise plans can create custom roles with exact permission grants.
How Roles Work
Every user in your organization has exactly one role. That role defines a set of permissions across eight categories: team management, billing, API keys, memories, settings, security, integrations, and SCIM. Permissions are evaluated on every request — both in the dashboard UI (pages are hidden if you lack permission) and in the API (requests return 403 Forbidden).
- Organization-scoped. Roles are defined per organization. A user can have different roles in different organizations.
- System vs. custom. System roles are built-in and cannot be modified or deleted. Custom roles (Enterprise only) let you create tailored permission sets for your team’s specific needs.
- No implicit inheritance. Each role has an explicit list of granted permissions. Nothing is assumed — if a permission isn’t listed, it’s denied.
System Roles
MemorySync ships with five system roles. These cover the most common team structures and cannot be edited or deleted.
| Role | Permissions | Best For |
|---|---|---|
| Owner | All permissions. The only role that can manage billing, delete the organization, and transfer ownership. | Founders, CTO |
| Admin | Everything except billing management and organization deletion. Can manage team, security settings, SSO, SCIM, API keys, integrations. | Engineering leads, DevOps |
| Developer | Create and manage API keys, read and write memories, manage own integrations, view audit logs. Cannot change security settings or manage team. | Engineers building with the API |
| Analyst | Read-only access to memories, full access to exports, view audit logs. Cannot create API keys or modify any data. | Data analysts, compliance reviewers |
| Billing Admin | View and manage billing, payment methods, invoices, and cost allocation tags. No access to memories, API keys, or security settings. | Finance team |
Permission Categories
Permissions are organized into eight categories. Each permission is a simple boolean — either granted or not. Some permissions are marked as dangerous, meaning they can cause irreversible changes (like deleting an organization or revoking all API keys).
| Category | Permissions |
|---|---|
| Team | team.view, team.invite, team.manage, team.remove |
| Billing | billing.view, billing.manage |
| API Keys | api.keys.create, api.keys.revoke, api.keys.view |
| Memories | memories.read, memories.write, memories.delete, memories.export |
| Settings | settings.view, settings.manage |
| Security | security.view, security.manage, security.sso.manage, security.audit.view, security.audit.export |
| Integrations | integrations.view, integrations.manage |
| SCIM | scim.view, scim.manage |
team.remove, api.keys.revoke, memories.delete, and billing.manage are flagged as dangerous. When creating custom roles, these permissions show a warning indicator in the dashboard. Assigning them requires explicit confirmation.Custom Roles
Enterprise plans can create custom roles with exactly the permissions their team needs. Custom roles are useful when none of the system roles fit a particular job function — for example, a “Security Reviewer” who can view audit logs and security settings but cannot modify them.
| Field | Description |
|---|---|
| Name & Slug | A human-readable name and a URL-safe slug (auto-generated). The slug is used in API responses and audit logs. |
| Description | A brief description of who this role is for and what it allows. |
| Color & Icon | Visual identifiers shown in the dashboard next to users who have this role. |
| Inherits From | Optionally inherit permissions from a system role as a starting point, then add or remove individual permissions. |
| Requires MFA | If enabled, users with this role must have MFA enabled on their account. Useful for high-privilege roles. |
| Max API Keys | Limit the number of API keys a user with this role can create. Set to 0 to prevent API key creation entirely. |
| Permissions | A JSON permissions map. Each permission category has individual grants that you toggle on or off. |
How Roles Are Assigned
Roles can be assigned through four channels. The first match wins — if a user has a role from SCIM group mapping, that takes precedence over the SSO JIT default.
- Direct assignment. An admin assigns a role to a user in Settings → Team. This is the most explicit method and always takes precedence.
- Invite. When inviting a new user, the inviter picks a role. That role is applied when the invite is accepted.
- SSO JIT provisioning. When a user logs in via SSO for the first time and JIT is enabled, they receive the
jit_default_roleconfigured in SSO settings. Group-to-role mapping in the IdP can override this. - SCIM provisioning. SCIM-provisioned users get the
default_rolefrom the SCIM configuration. Group mappings can override this based on IdP group membership.
Role Impact Simulation
Before changing a user’s role or modifying a custom role’s permissions, you can preview the impact using the role simulation feature. This lets you see exactly what would change without actually applying it.
- What changes. The simulation shows which permissions would be added, which would be removed, and which stay the same.
- Affected users. When editing a custom role, the simulation shows how many users currently have that role and would be affected by the change.
- Scope. Simulations can be run against the full team to understand the blast radius of a role change.
Simulations are available in the dashboard under Settings → Roles & Permissions → Simulate. Simulation results are saved with a timestamp and can be referenced later in audit logs.
Troubleshooting
- User has fewer permissions than expected. Check if the user’s role was overridden by SCIM or SSO group mapping. Look at the user’s profile in Settings → Team to see which role they have and how it was assigned (direct, SSO, or SCIM).
- Custom role not taking effect. Changes to a custom role’s permissions are picked up on the next login. Have the user log out and back in to refresh their permissions.
- API key returning 403 for actions the user can do in the dashboard. API key permissions are a subset of the user’s role permissions. Check the scopes granted when the API key was created.
- MFA required but user has no MFA set up. If a custom role requires MFA and the user hasn’t enrolled, they are prompted to set up MFA on their next login. Until they do, their access is limited to profile settings.
- Cannot delete a system role. System roles (Owner, Admin, Developer, Analyst, Billing Admin) are built-in and cannot be modified or deleted. Create a custom role instead.