2020-07-27 10:59:08 -07:00
---
layout: docs
2024-12-04 11:01:09 -05:00
page_title: Role resource
description: >-
Learn about using the role resource to group permissions which are then granted to any principal assigned to the role. Understand role attributes.
2020-07-27 10:59:08 -07:00
---
# Roles
2020-10-11 16:15:26 -04:00
A role is a resource
that contains a collection of [permissions][]
which are granted to any principal assigned to the role.
2021-06-09 07:55:02 -05:00
[Users][], [groups][], and [managed groups][] are principals
2020-10-11 16:15:26 -04:00
which allows either to be assigned to a role.
2020-11-20 09:27:21 -08:00
A role can be defined within any [scope][].
2020-10-11 16:15:26 -04:00
A role can be assigned to principals from any scope.
2020-07-27 10:59:08 -07:00
## Attributes
2020-10-11 16:15:26 -04:00
A role has the following configurable attributes:
2020-07-27 10:59:08 -07:00
2020-10-11 16:15:26 -04:00
- `name` - (optional)
If set, the `name` must be unique within the role's [project][].
2020-07-27 10:59:08 -07:00
2020-10-11 16:15:26 -04:00
- `description` - (optional)
2020-07-27 10:59:08 -07:00
2023-07-07 14:42:11 -04:00
## Referenced by
2020-07-27 10:59:08 -07:00
2020-10-11 16:15:26 -04:00
- [Group][]
2021-06-09 07:55:02 -05:00
- [Managed Group][]
2020-10-11 16:15:26 -04:00
- [Project][]
- [User][]
2020-07-27 10:59:08 -07:00
2023-01-20 18:17:34 -05:00
[group]: /boundary/docs/concepts/domain-model/groups
[groups]: /boundary/docs/concepts/domain-model/groups
[managed group]: /boundary/docs/concepts/domain-model/managed-groups
[managed groups]: /boundary/docs/concepts/domain-model/managed-groups
[permissions]: /boundary/docs/concepts/security/permissions
[project]: /boundary/docs/concepts/domain-model/scopes#projects
[scope]: /boundary/docs/concepts/domain-model/scopes
[user]: /boundary/docs/concepts/domain-model/users
[users]: /boundary/docs/concepts/domain-model/users
2020-10-12 17:40:42 -04:00
2023-07-07 14:42:11 -04:00
## Service API docs
2020-10-12 17:40:42 -04:00
The following services are relevant to this resource:
2023-01-20 18:17:34 -05:00
- [Role Service](/boundary/api-docs/role-service)
2022-07-12 12:29:35 -07:00
## Tutorial
2023-01-20 18:17:34 -05:00
Refer to the [Managed Roles and Permissions with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-roles) tutorial to learn how to create a role in Boundary.
