From 460968179c230237307fec2367f2c135932dd7d0 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Tue, 29 Mar 2022 21:11:59 +0200 Subject: [PATCH] api_docs: Add roles and permissions page to API documentation. Adds a non-endpoint specific page to the API documentation about organization-level roles and permissions for users in order to highlight important and useful information for clients and API users. Also, adds links to new documentation page in related areas of the API documentation. --- templates/zerver/api/roles-and-permissions.md | 120 +++++++++++ templates/zerver/api/sidebar_index.md | 1 + zerver/openapi/zulip.yaml | 200 ++++++++++++------ 3 files changed, 255 insertions(+), 66 deletions(-) create mode 100644 templates/zerver/api/roles-and-permissions.md 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