Custom Objects Permissions

Important: Relationship-based access control is in early access. This API is subject to change and should not be used in a production environment. Visit the ReBAC EAP forum to provide feedback.

You can customize the authorization of requests by implementing policies. Every object type and relationship type has a policy to define role-based access control (RBAC). Every object type has zero or more policies to define relationship-based access control (ReBAC).

The RBAC policy on an object type or relationship type grants create, read, update, and delete permissions to agents and end users for object records or relationship records of that type. If you provision agent and end user RBAC read permission, then they can read the type as well.

A ReBAC policy on an object type ot grants additional read and update permissions to agents and end users. Each ReBAC policy specifies a relationship type with a source object type of zen:user and a target object type of ot. If an existing relationship record of that type points from the user making the request to an object record of type ot, then the ReBAC policy grants read and update permissions to the object record. In other words, the RBAC policy on the object type might forbid an agent or end user from reading or updating object records of that type, but a ReBAC policy on the object type can allow the user to read or update specific object records of the type.

JSON Format

Permissions are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
rbac object false false The RBAC policy for the object type
rebac object false false

Relationship type policies are defined by a JSON object with the following properties:

Name Type Writable Required Comment
rbac object yes yes The RBAC policy for the relationship type

An RBAC policy consists of a JSON object with the following properties:

Name Type Writable Required Comment
admin object yes no The CRUD permission definition for admins
agent object yes no The CRUD permission definition for agents
end_user object yes no The CRUD permission definition for end users
custom object yes no The CRUD permission definitions for custom agent roles. In this object, each property maps a custom agent role to a CRUD permission definition.

A ReBAC policy consists of a JSON object with the following properties:

Name Type Writable Required Comment
admin object yes no The RU (read/update) permission definition for admins
agent object yes no The RU permission definition for agents
end_user object yes no The RU permission definition for end users
custom object yes no The RU permission definitions for custom agent roles. In this object, each property maps a custom agent role to an RU permission definition.

A CRUD permission definition consists of a JSON object with the following properties:

Name Type Writable Required Comment
create boolean yes no
read boolean yes no
update boolean yes no
delete boolean yes no

An RU (read/update) permission definition consists of a JSON object with the following properties:

Name Type Writable Required Comment
read boolean yes no
update boolean yes no

Policies for custom agent roles

On the Enterprise plan, admins can define custom agent roles and assign those roles to any agent. See Creating custom roles and assigning agents (Enterprise) in Help Center.

An RBAC or ReBAC policy can have a custom object that defines the permissions of an agent with a custom agent role. The object specifies the ID of the custom role and a permissions policy, which can either be a CRUD or a RU policy depending on whether the parent is RBAC or ReBAC, respectively.

You can get the id of the custom role using the List Custom Roles endpoint. Custom role IDs are not validated to see if roles exist for them.

If any permission value is left unspecified (create, read, update or delete for a CRUD permission definition, and read or update for an RU permission definition) within a custom agent role policy, the unspecified values will be populated with the value false.

If a request is made by a user with a custom agent role, but no policy has been created for that custom agent role, the request will be handled with the existing agent permissions for the object or relationship type that is the subject of the request.

If a request is made by a user with a custom agent role and a policy exists for that custom role, that policy will override the normal agent permissions granted to the user.

Example
{
  "data": {
    "rbac": {
      "agent": {
        "end_user": true,
        "read": true,
        "update": false,
        "delete": false
      },
      "custom": {
        "8237": {
          "create": false,
          "read": true,
          "update": true,
          "delete": false
        }
      }
    },
    "rebac": {
      "user_to_many_products": {
        "end_user": {
          "update": true
        },
        "custom": {
          "8237": {
            "read": true,
            "update": false
          }
        }
      }
    }
  }
}

Default role-based access control (RBAC) policy

When an object type or relationship type is created, a default RBAC policy is issued to the type. The default RBAC policy is used to enforce the authorization rules for any incoming requests on object records or relationship records associated with the object type or relationship type. The permissions defined in the default RBAC policy are as follows.

{
  "admin": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true
  },
  "agent": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true
  },
  "end_user": {
    "create": false,
    "read": false,
    "update": false,
    "delete": false
  }
}

Default relationship-based access control (ReBAC) policy

When a ReBAC policy is created on an object type, not all permissions need to be specified. If the definition omits some permissions, then their default values are as follows.

{
  "admin": {
    "read": true,
    "update": true
  },
  "agent": {
    "read": false,
    "update": false
  },
  "end_user": {
    "read": false,
    "update": false
  }
}

A final full example with all properties.

Example
{
  "rbac": {
    "agent": {
      "create": true,
      "delete": false,
      "read": true,
      "update": true
    },
    "custom": {
      "8237": {
        "create": false,
        "delete": false,
        "read": true,
        "update": true
      }
    },
    "end_user": {
      "read": true
    }
  },
  "rebac": {
    "user_to_many_products": {
      "custom": {
        "8237": {
          "read": true,
          "update": true
        }
      },
      "end_user": {
        "update": true
      }
    }
  }
}

Show Object Type Policies

  • GET /api/sunshine/objects/types/{object_type_key}/permissions

Returns the policies for the specified object type.

Allowed For
  • Agents
Parameters
Name Type In Required Description
object_type_key string Path true The key property is a unique identifier for the object type that you define yourself
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{object_type_key}/permissions \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": {
    "rbac": {
      "admin": {
        "create": true,
        "delete": true,
        "read": true,
        "update": true
      },
      "agent": {
        "create": true,
        "delete": true,
        "read": true,
        "update": true
      },
      "end_user": {
        "create": false,
        "delete": false,
        "read": false,
        "update": false
      }
    }
  }
}

Update Object Type Policies

  • PATCH /api/sunshine/objects/types/{object_type_key}/permissions

Updates the policies for the specified object type. If no updates to the RBAC policy have occurred, then the default RBAC policy is used. If a request creates a new ReBAC policy for an object type and a property is omitted from the ReBAC policy, then the corresponding property from the default ReBAC policy is used. If a request updates an existing RBAC policy or ReBAC policy and a property is omitted, then the corresponding property from the previous policy is used.

Allowed For
  • Admins
Parameters
Name Type In Required Description
object_type_key string Path true The key property is a unique identifier for the object type that you define yourself
Using curl

For clarity, the example places the JSON in a separate file and imports it into the cURL statement.

policies.json

{
  "data": {
    "rbac": {
      "agent": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      },
      "end_user": {
        "read": true
      }
    },
    "rebac": {
      "user_to_many_products": {
        "end_user": {
          "update": true
        }
      }
    }
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{object_type_key}/permissions \
  -d @policies.json \
  -H "Content-Type: application/merge-patch+json" -X PATCH \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": {
    "rbac": {
      "admin": {
        "create": true,
        "delete": true,
        "read": true,
        "update": true
      },
      "agent": {
        "create": true,
        "delete": false,
        "read": true,
        "update": true
      },
      "end_user": {
        "create": false,
        "delete": false,
        "read": true,
        "update": false
      }
    },
    "rebac": {
      "user_to_many_products": {
        "admin": {
          "read": true,
          "update": true
        },
        "agent": {
          "read": false,
          "update": false
        },
        "end_user": {
          "read": false,
          "update": true
        }
      }
    }
  }
}

Show Relationship Type Policies

  • GET /api/sunshine/relationships/types/{relationship_type_key}/permissions

Returns the policies for the specified relationship type.

Allowed For
  • Agents
Parameters
Name Type In Required Description
relationship_type_key string Path true The key of the relationship type
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/types/{relationship_type_key}/permissions \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": {
    "rbac": {
      "admin": {
        "create": true,
        "delete": true,
        "read": true,
        "update": true
      },
      "agent": {
        "create": true,
        "delete": true,
        "read": true,
        "update": true
      },
      "end_user": {
        "create": false,
        "delete": false,
        "read": false,
        "update": false
      }
    }
  }
}

Update Relationship Type Policies

  • PATCH /api/sunshine/relationships/types/{relationship_type_key}/permissions

Updates the policies for the specified relationship type. If no updates to the RBAC policy have occurred, then the default RBAC policy is used. ReBAC policies cannot be created for relationship types. If a request updates an existing RBAC policy or ReBAC policy and a property is omitted, then the corresponding property from the previous policy is used.

Allowed For
  • Admins
Parameters
Name Type In Required Description
relationship_type_key string Path true The key of the relationship type
Using curl

For clarity, the example places the JSON in a separate file and imports it into the cURL statement.

policies.json

{
  "data": {
    "rbac": {
      "agent": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      },
      "end_user": {
        "read": true
      }
    }
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/sunshine/relationships/types/{relationship_type_key}/permissions \
  -d @policies.json \
  -H "Content-Type: application/merge-patch+json" -X PATCH \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": {
    "rbac": {
      "admin": {
        "create": true,
        "delete": true,
        "read": true,
        "update": true
      },
      "agent": {
        "create": true,
        "delete": false,
        "read": true,
        "update": true
      },
      "end_user": {
        "create": false,
        "delete": false,
        "read": true,
        "update": false
      }
    },
    "rebac": {}
  }
}