diff --git a/templates/zerver/api/roles-and-permissions.md b/templates/zerver/api/roles-and-permissions.md new file mode 100644 index 0000000000..1fd005f772 --- /dev/null +++ b/templates/zerver/api/roles-and-permissions.md @@ -0,0 +1,120 @@ +# Roles and permissions + +Zulip offers several levels of permissions based on a +[user's role](/help/roles-and-permissions) in a Zulip organization. + +Here are some important details to note when working with these +roles and permissions in Zulip's API: + +## A user's role + +A user's account data include a `role` property, which contains the +user's role in the Zulip organization. These roles are encoded as: + +* Organization owner: 100 + +* Organization administrator: 200 + +* Organization moderator: 300 + +* Member: 400 + +* Guest: 600 + +User account data also include these boolean properties that duplicate +the related roles above: + +* `is_owner` specifying whether the user is an organization owner. + +* `is_admin` specifying whether the user is an organization administrator. + +* `is_guest` specifying whether the user is a guest user. + +These are intended as conveniences for simple clients, and clients +should prefer using the `role` field, since only that one is updated +by the [events API](/api/get-events). + +Note that [`POST /register`](/api/register-queue) also returns an +`is_moderator` boolean property specifying whether the current user is +an organization moderator. + +Additionally, user account data include an `is_billing_admin` property +specifying whether the user is a billing administrator for the Zulip +organization, which is not related to one of the roles listed above, +but rather allows for specific permissions related to billing +administration in [paid Zulip Cloud plans](https://zulip.com/plans/). + +### User account data in the API + +Endpoints that return the user account data / properties mentioned +above are: + +* [`GET /users`](/api/get-users) + +* [`GET /users/{user_id}`](/api/get-user) + +* [`GET /users/{email}`](/api/get-user-by-email) + +* [`GET /users/me`](/api/get-own-user) + +* [`GET /events`](/api/get-events) + +* [`POST /register`](/api/register-queue) + +Note that the [`POST /register` endpoint](/api/register-queue) returns +the above boolean properties to describe the role of the current user, +when `realm_user` is present in `fetch_event_types`. + +Additionally, the specific events returned by the +[`GET /events` endpoint](/api/get-events) containing data related +to user accounts and roles are the [`realm_user` add +event](/api/get-events#realm_user-add), and the +[`realm_user` update event](/api/get-events#realm_user-update). + +## Permission levels + +Many areas of Zulip are customizable by the roles +above, such as (but not limited to) [configuring message editing and +deletion](/help/configure-message-editing-and-deletion) and +[streams permissions](/help/stream-permissions). The potential +permission levels are: + +* Everyone / Any user including Guests (least restrictive) + +* Members + +* Full members + +* Moderators + +* Administrators + +* Owners + +* Nobody (most restrictive) + +These permission levels and policies in the API are designed to be +cutoffs in that users with the specified role and above have the +specified ability or access. For example, a permission level documented +as 'moderators only' includes organization moderators, administrators, +and owners. + +Note that specific settings and policies in the Zulip API that use these +permission levels will likely support a subset of those listed above. + +## Determining if a user is a full member + +When a Zulip organization has set up a [waiting period before new members +turn into full members](/help/restrict-permissions-of-new-members), +clients will need to determine if a user's account has aged past the +organization's waiting period threshold. + +The `realm_waiting_period_threshold`, which is the number of days until +a user's account is treated as a full member, is returned by the +[`POST /register` endpoint](/api/register-queue) when `realm` is present +in `fetch_event_types`. + +Clients can compare the `realm_waiting_period_threshold` to a user +accounts's `date_joined` property, which is the time the user account +was created, to determine if a user has the permissions of a full +member or a new member. diff --git a/templates/zerver/api/sidebar_index.md b/templates/zerver/api/sidebar_index.md index 1f9cffcb12..a9c0778f40 100644 --- a/templates/zerver/api/sidebar_index.md +++ b/templates/zerver/api/sidebar_index.md @@ -19,6 +19,7 @@ * [API keys](/api/api-keys) * [Configuring the Python bindings](/api/configuring-python-bindings) * [Error handling](/api/rest-error-handling) +* [Roles and permissions](/api/roles-and-permissions) * [Client libraries](/api/client-libraries) * [API changelog](/api/changelog) diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 949ce9a8a5..b070d1031d 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -469,7 +469,7 @@ paths: - type: object additionalProperties: false description: | - When the role of a user changes. + When the [role](/help/roles-and-permissions) of a user changes. properties: user_id: type: integer @@ -478,7 +478,7 @@ paths: role: type: integer description: | - The new role of the user in integer. + The new [role](/api/roles-and-permissions) of the user. enum: - 100 - 200 @@ -3573,7 +3573,8 @@ paths: add_custom_emoji_policy: type: integer description: | - The policy for which users can add custom emoji in this organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can add custom emoji in this organization. allow_edit_history: type: boolean description: | @@ -3598,7 +3599,8 @@ paths: bot_creation_policy: type: integer description: | - The policy for which users can create bot users in this organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can create bot users in this organization. community_topic_editing_limit_seconds: type: integer description: | @@ -3611,16 +3613,16 @@ paths: create_public_stream_policy: type: integer description: | - The policy for which users can - create public streams in this organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can create public streams in this organization. **Changes**: Before Zulip 5.0 (feature level 102), permission to create streams was controlled by the `create_stream_policy` setting. create_private_stream_policy: type: integer description: | - The policy for which users can - create private streams in this organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can create private streams in this organization. **Changes**: Before Zulip 5.0 (feature level 102), permission to create streams was controlled by the `create_stream_policy` setting. @@ -3655,27 +3657,32 @@ paths: edit_topic_policy: type: integer description: | - The policy for which users can edit topics of any message. + The [policy][permission-level] for which users can edit topics of any message. - 1 = members only - 2 = admins only - - 3 = full members only + - 3 = [full members][calc-full-member] only - 4 = moderators only - 5 = everyone **Changes**: New in Zulip 5.0 (feature level 75), replacing the previous `allow_community_topic_editing` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member email_address_visibility: type: integer description: | - The policy for which users in this organization can see the - real email addresses of other users. + The [policy][permission-level] for which users in this organization can see + the real email addresses of other users. - 1 = everyone - 2 = members only - 3 = administrators only - 4 = nobody (though note that administrators can change this setting). - 5 = moderators only + + [permission-level]: /api/roles-and-permissions#permission-levels email_changes_disabled: type: boolean description: | @@ -3737,16 +3744,16 @@ paths: invite_to_realm_policy: type: integer description: | - The policy for which users can invite other users - to join the organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can invite other users to join the organization. **Changes**: New in Zulip 4.0 (feature level 50) replacing the previous `invite_by_admins_only` boolean. invite_to_stream_policy: type: integer description: | - The policy for which users can add other users to streams in this - organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can add other users to streams in this organization. logo_source: type: string description: | @@ -3794,14 +3801,18 @@ paths: move_messages_between_streams_policy: type: integer description: | - The policy for which users can move messages from one stream to another. + The [policy][permission-level] for which users can move messages from + one stream to another. - 1 = Members only - 2 = Administrators only - - 3 = Full members only + - 3 = [Full members][calc-full-member] only - 4 = Moderators only **Changes**: New in Zulip 4.0 (feature level 56) + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member name: type: string description: | @@ -3854,7 +3865,8 @@ paths: private_message_policy: type: integer description: | - Policy for [who can send private messages](/help/restrict-private-messages) + [Policy](/api/roles-and-permissions#permission-levels) + for [who can send private messages](/help/restrict-private-messages) in this organization. - 1 = Everyone @@ -3876,15 +3888,17 @@ paths: user_group_edit_policy: type: integer description: | - The organization's policy for [who can manage user groups - ][user-group-permissions]. + The organization's [policy][permission-level] for + [who can manage user groups][user-group-permissions]. - 1 = All members can create and edit user groups - 2 = Only organization administrators can create and edit user groups - - 3 = Only full members can create and edit user groups + - 3 = Only [full members][calc-full-member] can create and edit user groups - 4 = Only organization administrators and moderators can create and edit user groups [user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member video_chat_provider: type: integer description: | @@ -3893,16 +3907,19 @@ paths: type: integer description: | Members whose accounts have been created at least this many days ago - will be treated as [full members](/help/restrict-permissions-of-new-members) + will be treated as [full members][calc-full-member] for the purpose of settings that restrict access to new members. + + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member wildcard_mention_policy: type: integer description: | - The policy for who can use wildcard mentions in large streams. + The [policy][permission-level] for who can use wildcard mentions in + large streams. - 1 => Any user can use wildcard mentions in large streams. - 2 => Only members can use wildcard mentions in large streams. - - 3 => Only full members can use wildcard mentions in large streams. + - 3 => Only [full members][calc-full-member] can use wildcard mentions in large streams. - 4 => Only stream and organization administrators can use wildcard mentions in large streams. - 5 => Only organization administrators can use wildcard mentions in large streams. - 6 => Nobody can use wildcard mentions in large streams. @@ -3913,6 +3930,9 @@ paths: **Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in Zulip 4.0 (feature level 62). + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member additionalProperties: false example: { @@ -6445,7 +6465,7 @@ paths: - 400 - 600 description: | - [Organization-level role](/help/roles-and-permissions) of the user. + [Organization-level role](/api/roles-and-permissions) of the user. Possible values are: - Organization owner => 100 @@ -8538,7 +8558,7 @@ paths: - name: role in: query description: | - New [role](/help/roles-and-permissions) for the user. Roles are encoded as: + New [role](/api/roles-and-permissions) for the user. Roles are encoded as: - Organization owner: 100 - Organization administrator: 200 @@ -10669,16 +10689,19 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can upload new custom emoji in this - organization. + The [policy][permission-level] for which users can upload new custom emoji + in this organization. - 1 = Members only - 2 = Administrators only - - 3 = Full members only + - 3 = [Full members][calc-full-member] only - 4 = Moderators only **Changes**: New in Zulip 5.0 (feature level 85) replacing the previous `realm_add_emoji_by_admins_only` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_allow_edit_history: type: boolean description: | @@ -10691,52 +10714,64 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - The policy defining which users can delete + The [policy][permission-level] defining which users can delete messages that they had sent. - 1 = members only - 2 = admins only - - 3 = full members only + - 3 = [full members][calc-full-member] only - 4 = admins and moderators only - 5 = everyone **Changes**: New in Zulip 5.0 (feature level 101), replacing the previous `allow_message_deleting` boolean; `true` corresponded to `everyone`, and `false` to `admins only`. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_bot_creation_policy: type: integer description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can create bot users in this organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can create bot users in this organization. realm_create_public_stream_policy: type: integer description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can create public streams in this organization. + The [policy][permission-level] for which users can create public streams + in this organization. - 1 = members only - 2 = admins only - - 3 = full members only + - 3 = [full members][calc-full-member] only - 4 = admins and moderators only **Changes**: Before Zulip 5.0 (feature level 102), permission to create streams was controlled by the `realm_create_stream_policy` setting. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_create_private_stream_policy: type: integer description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can create private streams in this organization. + The [policy][permission-level] for which users can create private streams + in this organization. - 1 = members only - 2 = admins only - - 3 = full members only + - 3 = [full members][calc-full-member] only - 4 = admins and moderators only **Changes**: Before Zulip 5.0 (feature level 102), permission to create streams was controlled by the `realm_create_stream_policy` setting. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_create_web_public_stream_policy: type: integer description: | @@ -10747,7 +10782,7 @@ paths: server-level setting enabled and the organization has enabled the `enable_spectator_access` realm setting. - The policy for which users can create web + The [policy][permission-level] for which users can create web public streams in this organization. Allowed values are: @@ -10757,23 +10792,26 @@ paths: - 7 = owners only **Changes**: Added in Zulip 5.0 (feature level 103). + + [permission-level]: /api/roles-and-permissions#permission-levels realm_invite_to_stream_policy: type: integer description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can add other users to streams in this - organization. + The [policy](/api/roles-and-permissions#permission-levels) + for which users can add other users to streams in this organization. realm_wildcard_mention_policy: type: integer description: | Present if `realm` is present in `fetch_event_types`. - The policy for who can use wildcard mentions in large streams. + The [policy][permission-level] for who can use wildcard mentions + in large streams. - 1 => Any user can use wildcard mentions in large streams. - 2 => Only members can use wildcard mentions in large streams. - - 3 => Only full members can use wildcard mentions in large streams. + - 3 => Only [full members][calc-full-member] can use wildcard mentions in large streams. - 4 => Only stream and organization administrators can use wildcard mentions in large streams. - 5 => Only organization administrators can use wildcard mentions in large streams. - 6 => Nobody can use wildcard mentions in large streams. @@ -10784,6 +10822,9 @@ paths: **Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in Zulip 4.0 (feature level 62). + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_default_language: type: string description: | @@ -10814,14 +10855,16 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users in this organization can see the - real email addresses of other users. + The [policy][permission-level] for which users in this organization can see + the real email addresses of other users. - 1 = everyone - 2 = members only - 3 = administrators only - 4 = nobody (though note that administrators can change this setting). - 5 = moderators only + + [permission-level]: /api/roles-and-permissions#permission-levels realm_email_changes_disabled: type: boolean description: | @@ -10841,30 +10884,38 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - Policy for [who can invite new users](/help/restrict-account-creation#change-who-can-send-invitations) + [Policy][permission-level] for [who can invite new + users](/help/restrict-account-creation#change-who-can-send-invitations) to join the organization: - 1 = Members only - 2 = Administrators only - - 3 = Full members only + - 3 = [Full members][calc-full-member] only - 4 = Moderators only - 6 = Nobody **Changes**: New in Zulip 4.0 (feature level 50) replacing the previous `realm_invite_by_admins_only` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_move_messages_between_streams_policy: type: integer description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can move messages from one stream to another. + The [policy][permission-level] for which users can move messages + from one stream to another. - 1 = Members only - 2 = Administrators only - - 3 = Full members only + - 3 = [Full members][calc-full-member] only - 4 = Moderators only **Changes**: New in Zulip 4.0 (feature level 56) + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_inline_image_preview: type: boolean description: | @@ -10982,8 +11033,10 @@ paths: Present if `realm` is present in `fetch_event_types`. Members whose accounts have been created at least this many days ago - will be treated as [full members](/help/restrict-permissions-of-new-members) + will be treated as [full members][calc-full-member] for the purpose of settings that restrict access to new members. + + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_digest_weekday: type: integer description: | @@ -10996,7 +11049,8 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - Policy for [who can send private messages](/help/restrict-private-messages) + [Policy](/api/roles-and-permissions#permission-levels) + for [who can send private messages](/help/restrict-private-messages) in this organization. - 1 = Everyone @@ -11006,15 +11060,17 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - The organization's policy for [who can manage user groups - ][user-group-permissions]. + The organization's [policy][permission-level] for + [who can manage user groups][user-group-permissions]. - 1 = All members can create and edit user groups - 2 = Only organization administrators can create and edit user groups - - 3 = Only full members can create and edit user groups. + - 3 = Only [full members][calc-full-member] can create and edit user groups. - 4 = Only organization administrators and moderators can create and edit user groups. [user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_default_code_block_language: type: string nullable: true @@ -11063,16 +11119,19 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - The policy for which users can edit topics of any message. + The [policy][permission-level] for which users can edit topics of any message. - 1 = members only - 2 = admins only - - 3 = full members only + - 3 = [full members][calc-full-member] only - 4 = moderators only - 5 = everyone **Changes**: New in Zulip 5.0 (feature level 75), replacing the previous `allow_community_topic_editing` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member realm_message_content_edit_limit_seconds: type: integer description: | @@ -11890,13 +11949,13 @@ paths: description: | Present if `realm_user` is present in `fetch_event_types`. - Whether the current user is an [organization administrator](/help/roles-and-permissions). + Whether the current user is an [organization administrator](/api/roles-and-permissions). is_owner: type: boolean description: | Present if `realm_user` is present in `fetch_event_types`. - Whether the current user is an [organization owner](/help/roles-and-permissions). + Whether the current user is an [organization owner](/api/roles-and-permissions). is_billing_admin: type: boolean description: | @@ -11910,7 +11969,7 @@ paths: description: | Present if `realm_user` is present in `fetch_event_types`. - Whether the current user is an [organization moderator](/help/roles-and-permissions). + Whether the current user is an [organization moderator](/api/roles-and-permissions). **Changes**: New in Zulip 4.0 (feature level 60). is_guest: @@ -11918,7 +11977,7 @@ paths: description: | Present if `realm_user` is present in `fetch_event_types`. - Whether the current user is a [guest user](/help/roles-and-permissions). + Whether the current user is a [guest user](/api/roles-and-permissions). enter_sends: deprecated: true type: boolean @@ -14074,15 +14133,18 @@ components: stream_post_policy: type: integer description: | - Policy for which users can post messages to the stream. + [Policy][permission-level] for which users can post messages to the stream. - 1 => Any user can post. - 2 => Only administrators can post. - - 3 => Only full members can post. + - 3 => Only [full members][calc-full-member] can post. - 4 => Only moderators can post. **Changes**: New in Zulip 3.0, replacing the previous `is_announcement_only` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member message_retention_days: type: integer nullable: true @@ -14687,15 +14749,18 @@ components: stream_post_policy: type: integer description: | - Policy for which users can post messages to the stream. + [Policy][permission-level] for which users can post messages to the stream. - 1 => Any user can post. - 2 => Only administrators can post. - - 3 => Only full members can post. + - 3 => Only [full members][calc-full-member] can post. - 4 => Only moderators can post. **Changes**: New in Zulip 3.0, replacing the previous `is_announcement_only` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member message_retention_days: type: integer nullable: true @@ -15303,7 +15368,7 @@ components: - 400 - 600 description: | - [Organization-level role](/help/roles-and-permissions) of the user. + [Organization-level role](/api/roles-and-permissions) of the user. Possible values are: - Organization owner => 100 @@ -15850,15 +15915,18 @@ components: name: stream_post_policy in: query description: | - Policy for which users can post messages to the stream. + [Policy][permission-level] for which users can post messages to the stream. - 1 => Any user can post. - 2 => Only administrators can post. - - 3 => Only full members can post. + - 3 => Only [full members][calc-full-member] can post. - 4 => Only moderators can post. **Changes**: New in Zulip 3.0, replacing the previous `is_announcement_only` boolean. + + [permission-level]: /api/roles-and-permissions#permission-levels + [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member schema: type: integer default: 1