Roles & Permissions
Autoheal decides what someone can do from the roles they hold. A role is a set of permissions. You give a role to a user, a user group or a service account, either on the organization or on one project.
To add users, create user groups and change who has access, see Managing Access.
Organizations and projects
Your organization is your company's Autoheal account. It holds your users, user groups, projects, sign-in settings and usage.
A project holds the work: agents, skills and runbooks, chats, runs and investigations, integrations, alerts, incidents, on-call, status pages, the catalog and memories. What's in one project isn't visible from another. Most organizations start with one project. Larger teams use a project per product or team.
Every project is part of one organization. Users belong to the organization and are given roles on the projects they work in.
Who can hold a role
| What it is | Where it lives | |
|---|---|---|
| User | A person who signs in to Autoheal | The organization |
| User group | A named set of users. A role given to a user group applies to everyone in it | The organization |
| Service account | An identity for automation, such as CI or a script. It calls the API with its own keys | The organization, or one project |
Roles
Autoheal has four built-in roles.
- Read-only: sees everything in a project except other users' chats, and changes nothing. For stakeholders who need visibility.
- Member: does the day-to-day work in a project. A Member chats with and runs agents. A Member creates and edits agents, skills, runbooks, triggers, catalog entries and memories. A Member starts investigations, responds to alerts, pages and incidents, and approves agent requests. Members create and change these, but deleting them is for Project Admins. Members can also add and remove on-call overrides. For engineers and responders. What agents may do stays bounded by the project's agent profiles and policies, which only Project Admins change. Member can only be given on a project.
- Project Admin: everything in a project, including its integrations, settings, service accounts and who has access to it. For the users who own a project.
- Org Admin: runs the organization: its users, user groups, projects, roles and sign-in settings. Org Admin holds no project content: an Org Admin who also works in a project needs a role there too.
Where a role applies
| Given on | Applies |
|---|---|
| A project | In that project only |
| The organization | In every project, and on the organization's own pages |
Read-only, Project Admin and Org Admin can be given on the organization. Read-only, Member and Project Admin can be given on a project.
How access adds up
Someone can hold roles in several ways at once: given to them directly, through each user group they're in, and on the organization. They can do everything any of those roles allows. Nothing removes access. A role on a project adds to what the organization gives. It never narrows it.
Each project's IAM and Users pages show, for everyone, their roles there and where each comes from: Direct, via a user group, or From organization.
Project creators and the last admin
- Whoever creates a project becomes its Project Admin.
- Your organization always keeps at least one Org Admin: the last one can't be removed.
- A project can be left without a Project Admin. An Org Admin can give someone the role again.
Permissions
Each permission is shown with its key, which is what the API checks. The tables are generated from the same definitions the server checks. The same lists are in the app: Roles in your organization's sidebar shows each role as a matrix of resources and verbs.
A key is a resource and a verb:
- read sees it.
- create makes a new one.
- delete removes one.
- update changes one that exists, including its parts and actions on it. This covers a user group's members, a status page's services and subscribers, and enabling, disabling, testing or rotating. Update never creates or deletes.
- run runs agents and tools.
In a project
What each role allows inside a project: the project it is granted on, or every project when it is granted on the organization.
Projects and access
| Action | Permission | Org Admin | Project Admin | Member | Read-only |
|---|---|---|---|---|---|
| See projects: the list, and each project's name, ID and how many users hold a role on it | project:read | yes | yes | yes | yes |
| Rename a project and edit its description | project:update | yes | yes | ||
| See who has access, and where each role comes from | access:read | yes | yes | yes | yes |
| Give roles to users, user groups and service accounts | access:create | yes | yes | ||
| Remove roles | access:delete | yes | yes | ||
| See service accounts | service_account:read | yes | yes | yes | |
| Create service accounts | service_account:create | yes | |||
| Rename, disable and enable service accounts | service_account:update | yes | |||
| Delete service accounts | service_account:delete | yes | |||
| Create and rotate service accounts' API keys | api_key:create | yes | |||
| Revoke service accounts' API keys | api_key:delete | yes |
Settings
| Action | Permission | Org Admin | Project Admin | Member | Read-only |
|---|---|---|---|---|---|
| See settings: a project's, or the organization's (such as just-in-time provisioning) | settings:read | yes | yes | yes | |
| Change settings: a project's, or the organization's (such as just-in-time provisioning) | settings:update | yes |
Integrations
| Action | Permission | Org Admin | Project Admin | Member | Read-only |
|---|---|---|---|---|---|
| See integrations and the webhook URL (never stored secrets); test a connection | integration:read | yes | yes | yes | |
| Add integrations and skill imports | integration:create | yes | |||
| Edit integrations and their context; import from them; regenerate webhook secrets | integration:update | yes | |||
| Remove integrations and skill imports | integration:delete | yes |
Agents, runs and investigations
| Action | Permission | Org Admin | Project Admin | Member | Read-only |
|---|---|---|---|---|---|
| See agents, skills, runbooks and evals, with their files and history; see runs and investigations, including raw tool output and remediation plans | registry:read | yes | yes | yes | |
| Create agents, skills and runbooks | registry:create | yes | yes | ||
| Edit agents, skills and runbooks | registry:update | yes | yes | ||
| Run an agent; start or re-run an investigation; send follow-up input, answer a run's question, stop a run, give feedback | registry:run | yes | yes | ||
| Delete agents, skills and runbooks, and runs and investigations | registry:delete | yes | |||
| See agent profiles | agent_profile:read | yes | yes | yes | |
| Edit agent profiles: which integrations, repositories and skills agents can use | agent_profile:update | yes | |||
| Remove agent profiles | agent_profile:delete | yes | |||
| See agent policies | agent_policy:read | yes | yes | yes | |
| Create agent policies | agent_policy:create | yes | |||
| Edit what agents may do without approval | agent_policy:update | yes | |||
| Delete agent policies | agent_policy:delete | yes | |||
| See triggers, their runs and the events they can start on; test a draft | trigger:read | yes | yes | yes | |
| Create triggers | trigger:create | yes | yes | ||
| Edit, enable and disable triggers | trigger:update | yes | yes | ||
| Delete triggers | trigger:delete | yes | |||
| Chat with agents and see your own chats | chat:create | yes | yes | ||
| Read everyone's non-private chats in the project | chat:read | yes | |||
| See tools and every tool call, with its arguments and output | tool:read | yes | yes | yes | |
| Register tools in the tool registry | tool:create | yes | |||
| Edit tools in the tool registry | tool:update | yes | |||
| See memories | memory:read | yes | yes | yes | |
| Create memories | memory:create | yes | yes | ||
| Edit memories | memory:update | yes | yes | ||
| Delete memories | memory:delete | yes | |||
| See approval requests and history | approval:read | yes | yes | yes | |
| Approve or reject agent requests | approval:update | yes | yes | ||
| See artifacts | artifact:read | yes | yes | yes | |
| Upload artifacts | artifact:create | yes | yes | ||
| Delete artifacts | artifact:delete | yes | |||
| See project insights | insights:read | yes | yes | yes |
Alerts, incidents and on-call
| Action | Permission | Org Admin | Project Admin | Member | Read-only |
|---|---|---|---|---|---|
| See alerts and alert groups | alert:read | yes | yes | yes | |
| Silence an alert group for a set time | alert:create | yes | yes | ||
| Change a silence; update alerts | alert:update | yes | yes | ||
| Remove a silence | alert:delete | yes | |||
| Create proactive actions | proactive_action:create | yes | yes | ||
| Act on proactive actions: accept, dismiss, assign or edit one | proactive_action:update | yes | yes | ||
| See incidents | incident:read | yes | yes | yes | |
| Declare incidents | incident:create | yes | yes | ||
| Update incident status | incident:update | yes | yes | ||
| See schedules, rotations, escalation paths and pages | oncall:read | yes | yes | yes | |
| Page someone | oncall_page:create | yes | yes | ||
| Acknowledge, re-escalate and resolve pages | oncall_page:update | yes | yes | ||
| Add schedule overrides (cover a shift) | oncall_override:create | yes | yes | ||
| Remove schedule overrides | oncall_override:delete | yes | yes | ||
| Create schedules, escalation paths and teams | oncall:create | yes | |||
| Edit schedules, rotations, escalation paths and teams | oncall:update | yes | |||
| Delete schedules, escalation paths and teams | oncall:delete | yes | |||
| See status pages | status_page:read | yes | yes | yes | |
| Post status updates | status_post:create | yes | yes | ||
| Edit, add to and resolve status updates | status_post:update | yes | yes | ||
| Delete status updates | status_post:delete | yes | |||
| Create status pages | status_page:create | yes | |||
| Configure status pages: services, custom domain and subscribers | status_page:update | yes | |||
| Delete status pages | status_page:delete | yes |
Catalog
| Action | Permission | Org Admin | Project Admin | Member | Read-only |
|---|---|---|---|---|---|
| See blueprints and entities | catalog:read | yes | yes | yes | |
| Create catalog entities | catalog:create | yes | yes | ||
| Edit catalog entities and their relations; re-run a sync | catalog:update | yes | yes | ||
| Delete catalog entities | catalog:delete | yes | |||
| Create blueprints (the catalog's schema) | blueprint:create | yes | |||
| Edit blueprints | blueprint:update | yes | |||
| Delete blueprints | blueprint:delete | yes |
On the organization
What each role allows on the organization's own pages, when it is granted on the organization. Member can only be granted on a project.
Projects and access
| Action | Permission | Org Admin | Project Admin | Read-only |
|---|---|---|---|---|
| See projects: the list, and each project's name, ID and how many users hold a role on it | project:read | yes | yes | yes |
| See who has access, and where each role comes from | access:read | yes | yes | yes |
| Give roles to users, user groups and service accounts | access:create | yes | ||
| Remove roles | access:delete | yes | ||
| See service accounts | service_account:read | yes | yes | yes |
| Create service accounts | service_account:create | yes | ||
| Rename, disable and enable service accounts | service_account:update | yes | ||
| Delete service accounts | service_account:delete | yes | ||
| Create and rotate service accounts' API keys | api_key:create | yes | ||
| Revoke service accounts' API keys | api_key:delete | yes | ||
| Create projects | project:create | yes | ||
| See the organization's users and their roles | user:read | yes | yes | yes |
| Invite users | user:create | yes | ||
| Remove a user from the organization (ends their roles, user group memberships, tokens and sessions) | user:delete | yes | ||
| See user groups and their members | group:read | yes | yes | yes |
| Create user groups | group:create | yes | ||
| Rename user groups; add and remove members | group:update | yes | ||
| Delete user groups | group:delete | yes | ||
| See roles and what each allows | role:read | yes | yes | yes |
| See the access log: every access change in the organization | audit:read | yes | yes | yes |
| See usage across projects | usage:read | yes | yes | yes |
Settings
| Action | Permission | Org Admin | Project Admin | Read-only |
|---|---|---|---|---|
| See settings: a project's, or the organization's (such as just-in-time provisioning) | settings:read | yes | yes | yes |
| Change settings: a project's, or the organization's (such as just-in-time provisioning) | settings:update | yes | ||
| See SSO and sign-in settings | auth_settings:read | yes | ||
| Add SSO connections | auth_settings:create | yes | ||
| Change SSO and sign-in settings; enable and disable connections | auth_settings:update | yes | ||
| Remove SSO connections | auth_settings:delete | yes |
Legacy roles
Before the roles above, Autoheal had three roles given on the organization: Viewer, Responder and Admin. Autoheal replaced each with the roles below. The project roles apply to every project your organization had at the time:
| Legacy role | Replaced by |
|---|---|
| Viewer | Read-only on each project |
| Responder | Member on each project |
| Admin | Org Admin on the organization, and Project Admin on each project |
Where someone already held a role on a project, they kept it. Autoheal added no role there. A project created since lists only the people given a role on it.
Autoheal no longer assigns legacy roles. SSO just-in-time provisioning gives new users a role on your organization's default project, Member unless you change it. See Single Sign-On.
To change anyone's roles, use your organization's IAM. See Managing Access.
SSO
Autoheal supports SAML 2.0 single sign-on. See Single Sign-On (SAML). Your identity provider says who someone is, and Autoheal decides what they can do. Autoheal doesn't read group and role attributes in the SAML assertion, so there is no group-to-role mapping to configure. Autoheal doesn't sync user groups from your identity provider. There is no SCIM provisioning. Give roles in Autoheal, to people or to user groups.
FAQ
What role should I give a new engineer?
Member on the projects they work in. Read-only on the organization lets them see every project, but also shows them the organization's users and their roles, user groups and service accounts. Give it only to users who should see those.
Can an Org Admin see every project's investigations?
Not by default. Org Admin runs the organization but holds no project content. Org Admins see every project in the organization's project list, and open only those they hold a role on. An Org Admin can give themselves a role on a project. Autoheal records it and emails the other admins (see Granting yourself access).
How do I give a team access to several projects?
An Org Admin creates a user group for the team. Then, on your organization's IAM, the Org Admin chooses Grant access, picks the user group and gives it a role on each project in turn. A Project Admin can also give the user group a role on their own project, from the project's IAM. Everyone in the user group gets the roles, and users who join the user group later get them too.
Can I restrict someone in one project who has a role on the organization?
No. A role on the organization applies in every project, and roles only add access. Give them roles on individual projects instead.
How fast does a change take effect?
Within a minute, in every open session and for every API key of a service account.
What happens to someone's work when I remove them?
Everything they had access to ends, and their API tokens stop working. What they built stays: agents, investigations, runbooks and history keep their author.