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 |
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_role configured in SSO settings. Group-to-role mapping in the IdP can override this.
- SCIM provisioning. SCIM-provisioned users get the default_role from 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.