Docs Security & access
Security & access
Roles and permissions
Access in Kumo.io comes only from roles. Grant a role across the whole account or on one workspace, use the nine built-in roles, or build your own from individual permissions.
How access works
- No role, no access. Kumo.io denies everything that a role doesn't explicitly allow. A member with no role assignment can't see account data.
- A role is a set of permissions, such as
workspace.readorsource.sync. - An assignment gives a person a role at a scope: either the whole account, or one workspace. A workspace-scoped assignment grants nothing outside that workspace.
- The same rules apply everywhere: in the web app, through the API, through the CLI and to API tokens, which act with their creator's permissions.
The built-in roles
Kumo.io ships nine system roles. You can't edit or delete them.
| Role | What it's for |
|---|---|
| Account owner | Everything, including account settings, billing and SAML configuration |
| Account admin | Everything the owner can do except change account settings and billing: workspaces, sources, views, policies, members, roles, tokens, SSO, SCIM and integrations |
| Account editor | Build and run things in every workspace: workspaces, sources, credentials, scopes, environments, views, policies, alerts and reports. No access to roles, billing or the audit log |
| Billing admin | Billing and subscriptions, plus cost, usage and the audit log. Read-only account details |
| Account auditor | Read everything across the account, plus the audit log, roles and assignments, API tokens and SSO settings. Change nothing |
| Account viewer | Read everything across the account. Change nothing |
| Workspace admin | Run one workspace: its sources (including deleting them), syncs, environments, views, exports, alerts and reports |
| Workspace editor | Day-to-day work in one workspace: sync sources, edit environments and views, manage alerts, annotations and reports |
| Source operator | Start syncs and watch their runs. Built for automation |
| Workspace auditor | Read one workspace, plus the audit log |
| Workspace viewer | Read one workspace |
| Workspace guest | View one workspace's environments and diagrams. Nothing else |
The account-level roles are meant to be granted on the whole account, and the workspace-level roles on one workspace.
Permissions worth knowing
A few capabilities belong to specific permissions, and therefore to specific roles:
| You want to | Permission | Built-in roles that have it |
|---|---|---|
| Manage members and invitations | member.manage | Account owner, Account admin |
| See and grant roles | iam.role.read, iam.assignment.write | Account owner, Account admin (Account auditor can see them) |
| See every API token in the account | iam.api_key.read | Account owner, Account admin, Account auditor |
| Configure OpenID Connect single sign-on | sso.manage | Account owner, Account admin |
| Configure SAML single sign-on | account.write | Account owner |
| Manage SCIM provisioning | scim.manage | Account owner, Account admin |
| Connect Slack and manage webhooks | integration.manage | Account owner, Account admin |
| Read the audit log | audit.read | Account owner, Account admin, Billing admin, Account auditor, Workspace auditor |
| Change billing | billing.write | Account owner, Billing admin |
Grant a role
You need the Account owner or Account admin role.
- Open Settings › Roles & Access.
- Pick the Role. System roles are marked "(system)".
- Pick the Member.
- Pick the Scope: Whole account, or one workspace.
- Select Grant Role.
The assignment takes effect on the next request. Granting the same role to the same person at the same scope twice has no effect.
To remove access, select the assignment in the list and revoke it. An account must always keep at least one Account owner, so Kumo.io won't let you revoke the last one. Grant Account owner to someone else first.
Only Account owners and Account admins can view roles. Anyone else who opens Roles & Access is told to ask one of them.
Limits on what you can grant
Kumo.io stops people from granting themselves, or anyone else, more than they hold:
- You can grant a built-in role only if it ranks at or below the highest built-in role you hold on the whole account. An Account admin can grant Workspace admin, but can't create another Account owner.
- Workspace-scoped assignments don't count toward that rank. Being Workspace admin on one workspace doesn't let you grant Workspace admin elsewhere.
- You can grant any role, built-in or custom, only if you already hold every permission in it. For example, an Account admin can't grant Billing admin, because it includes billing permissions the Account admin role lacks.
Revoking is never limited this way, because it only removes access.
Custom roles
When none of the built-in roles fits, create your own.
- Open Settings › Roles & Access.
- Under Create a Custom Role, enter a Key (snake_case), a Display name and, optionally, a Description.
- Tick the Permissions the role should have.
- Select Create Role.
The new role is immediately available in the Role list. Custom roles appear under Custom Roles, where you can Edit their permissions or Archive them. An archived role can no longer be granted.
The limits above apply to custom roles too: you can only grant a custom role whose permissions you already hold.
Hosted and self-hosted
Roles work the same way on both. On a hosted workspace, the people who belong to it are the members of the Kumo.io account that owns it. On a self-hosted installation you invite members under Settings › Members. Read Invite your team.
Accountability
Role changes, role assignments and API-token changes are recorded in the audit log, and so are refused attempts to do something a person isn't allowed to.