Management Permission Groups

A management permission group defines which agents can create, update, archive, and publish articles. It consists of a set of privileges, each of which is mapped to a user segment. Agents receive whichever privileges are associated with the user segments they belong to.

The types of privileges a permission group can define depends on your Guide plan:

• Guide Enterprise supports the edit and publish privileges
• Guide Professional supports the publish privilege
• Guide Lite does not allow creating or updating permission groups. However the publish privilege is still honored on any permission groups that exist when switching to Lite

Permission groups are defined at the account level, not the brand level. If you use a brand as the subdomain of a request, the API redirects the request to the account's primary subdomain.

You can use this API to define or change a permission group. However, you must use the Articles API to apply management permission groups to articles. You can change the definition of user segments using the User Segments API.

JSON format

Management permission groups have the following attributes:

Name	Type	Read-only	Mandatory	Comment
id	integer	yes	no	Automatically assigned when the permission group is created
name	string	no	no	Permission group name
edit	array	no	no	The ids of user segments that have edit privileges
publish	array	no	no	The ids of user segments that have publish privileges
created_at	timestamp	yes	no	When the permission group was created
updated_at	timestamp	yes	no	When the permission group was last updated
built_in	boolean	yes	no	Whether the permission group is built-in. Built-in permission groups cannot be modified

Example

{
  "permission_group": {
    "id":         42,
    "name":       "Printer Experts",
    "built_in":   false,
    "publish":    [123456],
    "edit":       [],
    "created_at": "2018-08-23 12:42:18 +0000",
    "updated_at": "2018-08-23 12:42:18 +0000"
  }
}

List Permission Groups

GET /api/v2/guide/permission_groups.json

Allowed for

• Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/permission_groups.json \
  -v -u {email_address}:{password}

Example Response

Status: 200 OK

{
  "permission_groups": [
    {
      "id":         42,
      "name":       "Printer Experts",
      "built_in":   false,
      "publish":    [123456],
      "edit":       [],
      "created_at": "2018-08-23 12:42:18 +0000",
      "updated_at": "2018-08-23 12:42:18 +0000"
    },
    {
      "id": 	    75,
      "name":       "Managers",
      "built_in":   true,
      "publish":    [],
      "edit":       [],
      "created_at": "2018-03-16 08:29:27 +0000",
      "updated_at": "2018-03-16 08:29:27 +0000"
    },
    ...
  ]
}

Show Permission Group

GET /api/v2/guide/permission_groups/{id}.json

Allowed for

• Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/permission_groups/{id}.json \
  -v -u {email_address}:{password}

Example Response

Status: 200 OK

{
  "permission_group": {
    "id":         42,
    "name":       "Printer Experts",
    "built_in":   false,
    "publish":    [12],
    "edit":       [34],
    "created_at": "2018-08-23 12:42:18 +0000",
    "updated_at": "2018-08-23 12:42:18 +0000"
  }
}

Create Permission Group

POST /api/v2/guide/permission_groups.json

Allowed for

• Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/permission_groups.json \
  -d '{ \
    "permission_group": { \
      "name": "Printer Experts", \
      "edit": [12, ...], \
      "publish": [34, ...] \
    } \
  }' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Example Response

Status: 201 Created

{
  "permission_group": {
    "id":         42,
    "name":       "Printer Experts",
    "built_in":   false,
    "publish":    [34, ...],
    "edit":       [12, ...],
    "created_at": "2018-08-23 12:42:18 +0000",
    "updated_at": "2018-08-23 12:42:18 +0000"
  }
}

Update Permission Group

PUT /api/v2/guide/permission_groups/{id}.json

Allowed for

• Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/permission_groups/{id}.json \
  -d '{ \
    "user_segment": { \
      "name": "Super Printer Experts", \
      "edit": [], \
      "publish": [42, ...], \
    } \
  }' \
  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
  "permission_group": {
    "id":         42,
    "name":       "Super Printer Experts",
    "built_in":   false,
    "publish":    [42, ...],
    "edit":       [],
    "created_at": "2018-08-23 12:42:18 +0000",
    "updated_at": "2018-08-24 00:42:15 +0000"
  }
}

Delete Permission Group

DELETE /api/v2/guide/permission_groups/{id}.json

Allowed for

• Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/permission_groups/{id}.json \
  -v -u {email_address}:{password} -X DELETE

Example Response

Status: 204 No Content