> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/platform-administration-console/security-model-rbac/user-groups.md).
# User Groups
User groups provide a way to define a hierarchy between users, enabling hierarchy based access control.
{% hint style="warning" %}
Make sure to get familiar with [access evaluation](#user-content-fn-1)[^1].
{% endhint %}
{% hint style="danger" %}
Each non-system user must belong to a user group. If you upgraded from an older version, all existing users are assigned to the default user group.
When a new user signs up, the user is assigned to the user group defined by the auth client.
When creating users through the admin webapp, automation, or via the API; you need to specify the user group manually.
{% endhint %}
### Configuring User Groups
User groups are configured and managed in the Corteza Admin webapp.
In the Admin webapp, navigate to the System :angle-right: User Groups to see the list of currently defined user groups. Click on the New User Group button in the top left corner to open up the editor.
Fill in the required fields and select the user groups this one reports to. Click on the Submit button to create the user group.
{% hint style="info" %}
Each user group may report to multiple user groups. Each user group may report to the same user group following paths with different names.
You can specify the path name in the [isDescendantOf ](#user-content-fn-1)[^1]function
{% endhint %}
After the user group is created, two new sections appear at the bottom of the page. You can assign users to the user group in the "User Group Members" section.
{% hint style="info" %}
The user group of a particular user can also be changed from the user edit screen. Locate the "User group" drop down select to change the user group.
Don’t forget to save your changes by clicking on the Submit button.
{% endhint %}
You can assign roles to the user group in the "Role membership" section.
### Additions
#### Auth Client Additions
Auth clients now specify the default user group newly created users are assigned to. The default user group (provisioned by Corteza) is assigned to all existing auth clients.
#### Contextual Role Expression
Contextual roles now provide a set of expressions you can use to evaluate hierarchy.
1. [`isDescendantOf`](#user-content-fn-1)[^1]
2. [`isDescendantOfC`](#user-content-fn-1)[^1]
3. [`isDescendantOfR`](#user-content-fn-1)[^1]
4. [`isDescendantOfU`](#user-content-fn-1)[^1]
5. `i`[`sDescendantOfD`](#user-content-fn-1)[^1]
We suggest you create a new contextual role which enables users access resources in lower user groups.
[^1]: Add link
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.planetcrust.com/platform-administration-console/security-model-rbac/user-groups.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.