Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Lauryn Menard 2022-03-29 21:11:59 +02:00 committed by Tim Abbott
parent 8bc2ac4b8d
commit 460968179c
3 changed files with 255 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
templates/zerver/api/roles-and-permissions.md Normal file
View File

@ -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.

1
templates/zerver/api/sidebar_index.md
View File

@ -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)

200
zerver/openapi/zulip.yaml
View File

@ -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