documentation/content/en/entities/Role.md

154 lines
4.0 KiB
Markdown
Raw Normal View History

Update content for 4.0 (part 1) (#991) * add rules * join date on profiles * deprecate follow scope * deprecate identity proofs * familiar followers * use definition lists instead of tables for defining activitypub properties * reformat notifications page into markdown * fix broken links to publicKey header * Application website is now nullable * update environment variables added and removed * fix typo * fix heading level * min_id and max_id can be used at the same time (3.3) * fix typo * new tootctl options * reformat tootctl page to use definition lists for params * add rules and configuration to Instance * fix typo * refactor instance api page * 3.3.0 duration on mutes * 3.3.0 mute_expires_at * improve section headings * 3.4.0 resend email confirmation api * 3.4.0 policy on push subscriptions * 3.4.0 add details to account registration error * refactor accounts api page and start adding relrefs to entity pages * 3.4.0 accounts/lookup api * add see also to accounts methods * add more see-also links * 3.5.0 appeal mod decisions * 3.5.0 reformat reports and add category/rule_ids params * document report entity and missing responses * fix typos * fix relrefs and url schema, add aliases to old urls * add archetypes for new methods/entities * update archetypes with see-also stubs * clearer presentation of rate limits * announcements api methods * refactor apps methods * refactor bookmarks methods + some anchors * refactor conversations methods * custom_emojis methods refactor * anchors * refactor directory methods * refactor domain_blocks methods * add see also to emails methods * fix page relref shortcodes to specific methods + refactor endorsements methods * min_id max_id * refactor favourites methods * refactor featured_tags methods * refactor filters methods, make path params consistent, i18n required shortcode * follow_requests methods * lists methods * markers methods * forgot to add entity links * media methods, also fix formatting of some json errors * mutes methods, add more see-also links * oembed methods * preferences methods * proofs methods * push methods * suggestions methods * 3.5.0 add new trend types, fix formatting * refactor streaming methods * refactor oauth methods * note that streaming api casts payload to string * refactor search methods * refactor polls methods * remove unnecessary link * reformat scheduled_statuses methods * reformat timelines methods * reformat statuses methods * 3.5.0 editing statuses * consistent use of array brackets in form data parameters * update dev setup guide, add vagrant and clean up text * add admin/accounts methods * 3.6 role entity * admin/accounts methods v2 * minor fix * stub admin/reports methods * document admin reports * add 403 example to methods archetype * cleanup entities for admin reports and add new attrs * 3.6.0 domain allows methods + normalize admin entity namespace * fix search-and-replace error * add aliases for admin entities * 3.6.0 canonical email blocks entity * 3.5.0 admin/retention api * 3.5.0 add admin::ip doc * 3.5.0 admin/reports * 3.6.0 admin/domain_allows * 3.5.0 admin/dimensions * 3.6.0 permissions and roles * minor formatting fix * add anchor link to headings * checkpoint * add update commands to dev env setup guide * change mentions of v3.6 to v4.0 * tootctl now uses custom roles * fix formatting * v2 instance api * update frontmatter, add better titles to pages * minor wording change * consistency * add more aliases * add placeholders and WIP notices * explain link pagination and stub out todos * switch baseURL to https * 422 on reports with rules but category!=violation * document bug fixes * fix typo * remove duplicate API method definition * s/tootsuite/mastodon for github links * remove unnecessary escaping * s/tootsuite/mastodon in Entity archetype * add missing nullable shortcode * clarify oauth scope when requesting a user token * api/v2/media now synchronous for images * DISALLOW_UNAUTHENTICATED_API_ACCESS * add undocumented env variables * add instance domain blocks and extended description api * add SMTP_ENABLE_STARTTLS * add description to SMTP_ENABLE_STARTTLS * take suggestions from open PRs * normalize links and flavour language * Fully document streaming API based on source code * Add mention of MIME types * bump to ruby 3.0.4 * clarify how to check on async media processing * validation of replies_policy * remove TODOs on admin account action * EmailDomainBlocks * IpBlocks * Admin::DomainBlock * remove TODOs * following hashtags * followed_tags * remove reference to unused parameter * add new oauth scopes for admin blocks and allows * fix command signature for i18n-tasks normalize * reformat code structure page * document fixes for following tags (assume 4.0.3) * Add warning about pre-4.0 hardcoded roles * add note about case sensitivity * remove use of 'simply' from docs * remove reference to silencing * add reference to IDN normalization for verified links * add lang parameter
2022-11-20 07:34:38 +01:00
---
title: Role
description: Represents a custom user role that grants permissions.
menu:
docs:
parent: entities
aliases: [
"/entities/role",
"/entities/Role",
"/api/entities/role",
"/api/entities/Role",
]
---
## Example
```json
{
"id": 3,
"name": "Owner",
"color": "#ff3838",
"position": 1000,
"permissions": 1,
"highlighted": true,
"created_at": "2022-09-08T22:48:07.983Z",
"updated_at": "2022-09-08T22:48:07.983Z"
},
```
## Attributes
### `id` {#id}
**Description:** The ID of the Role in the database.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
### `name` {#name}
**Description:** The name of the role.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `color` {#color}
**Description:** The hex code assigned to this role. If no hex code is assigned, the string will be empty.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `position` {#position}
**Description:** An index for the role's position. The higher the position, the more priority the role has over other roles.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
### `permissions` {#permissions}
**Description:** A bitmask that represents the sum of all permissions granted to the role.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
### `highlighted` {#highlighted}
**Description:** Whether the role is publicly visible as a badge on user profiles.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** The date that the role was created.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
### `updated_at` {#created_at}
**Description:** The date that the role was updated.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
## Permission flags
To determine the permissions available to a certain role, convert the `permissions` attribute to binary and compare from the least significant bit upwards. For convenience (and to prevent the terms from growing too long), permissions will be presented below using hexadecimal values.
0x1
: **Administrator**. Users with this permission bypass all permissions.
0x2
: **Devops**. Allows users to access Sidekiq and pgHero dashboards.
0x4
: **View Audit Log**. Allows users to see history of admin actions.
0x8
: **View Dashboard**. Allows users to access the dashboard and various metrics.
0x10
: **Manage Reports**. Allows users to review reports and perform moderation actions against them.
0x20
: **Manage Federation**. Allows users to block or allow federation with other domains, and control deliverability.
0x40
: **Manage Settings**. Allows users to change site settings.
0x80
: **Manage Blocks**. Allows users to block e-mail providers and IP addresses.
0x100
: **Manage Taxonomies**. Allows users to review trending content and update hashtag settings.
0x200
: **Manage Appeals**. Allows users to review appeals against moderation actions.
0x400
: **Manage Users**. Allows users to view other users' details and perform moderation actions against them.
0x800
: **Manage Invites**. Allows users to browse and deactivate invite links.
0x1000
: **Manage Rules**. Allows users to change server rules.
0x2000
: **Manage Announcements**. Allows users to manage announcements on the server.
0x4000
: **Manage Custom Emojis**. Allows users to manage custom emojis on the server.
0x8000
: **Manage Webhooks**. Allows users to set up webhooks for administrative events.
0x10000
: **Invite Users**. Allows users to invite new people to the server.
0x20000
: **Manage Roles**. Allows users to manage and assign roles below theirs.
0x40000
: **Manage User Access**. Allows users to disable other users' two-factor authentication, change their e-mail address, and reset their password.
0x80000
: **Delete User Data**. Allows users to delete other users' data without delay.
## See also
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/role_serializer.rb" caption="app/serializers/rest/role_serializer.rb" >}}