> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/organization-administration/roles-and-permissions.md).

# Roles and permissions

Custom roles define a set of permissions for people with similar responsibilities. Use the permission matrix to configure a role, then assign it to the appropriate members.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F7Y5zucn83VOu5NVPvk5C%2FG090.mp4?alt=media&token=e6477554-d62e-4b4a-830f-93a4e7aacaf7>" %}

## Before you start

Start with a responsibility, such as reviewing releases or managing invitations, and list the operations it needs. A role defines permitted operations; [groups](https://docs.stackai.com/guides-and-quickstarts/organization-administration/groups-and-membership.md) collect people for shared resource access. Check both when diagnosing why a person can or cannot open a project.

You need permission to manage roles and member access.

## Create and configure a role

Open Settings → Roles and compare the permission matrix.

![Roles permission matrix](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/u0JWXlNbl1gpPnafBNPm/assets/g090-g090-01-matrix.png)

Review organization-level and project-level permissions together when choosing a role.

Select Add Role and enter a descriptive name and purpose.

![Add Role name and purpose](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/zN1zEyv5izNYTPN8daWB/assets/g090-g090-02-create.png)

The description should explain the responsibilities the role supports.

Review the new role's permission column and enable the required operations.

![Custom role permission column](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/zF780b6w26m1ySOiInDe/assets/g090-g090-03-permissions.png)

Check the saved selections rather than assuming a custom role inherits another role's access.

## Assign and verify the role

In Members, select Change Role for the intended member and choose the custom role.

![Member Change Role selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/7hsr43OgaG0GXQdS0KiK/assets/g090-g090-04-assign.png)

Confirm the affected account and permission scope before saving.

Have the member check the available settings and project controls with their own account.

![Member account settings and project controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/YuxmOR4CsCq7DX1tNShx/assets/g090-g090-05-test.png)

Use explicit access results to confirm the role's effect.

## Remove an unused role

Review Delete Role and any requirement to assign a replacement role.

![Delete Role and replacement requirement](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/7rlhEe5Ql34aQjVX3zIr/assets/g090-g090-06-delete.png)

Resolve affected memberships before removing a role from the organization.

Confirm that each affected member has the intended continuing role.

![Member roles after reassignment](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/vyoCb8tOnV3hI0XlFRa4/assets/g090-g090-07-restore.png)

Remove an unused custom role only after its assignments and purpose have been reviewed.

## Important behavior

Review both organization and project permissions. Check the saved selections before assigning a custom role.

If a role is in use, resolve its member assignments before deleting it.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/organization-administration/roles-and-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
