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

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

Name Type Writable Required Comment
rbac object yes no The RBAC policy for the object type
rebac object yes no The ReBAC policies for the object type. In this object, each property maps a relationship type key to a ReBAC policy.

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

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

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
Example
{
  "data": {
    "rbac": {
      "agent": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      },
      "end_user": {
        "read": true
      }
    },
    "rebac": {
      "user_to_many_products": {
        "end_user": {
          "update": true
        }
      }
    }
  }
}

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

Show Policies

GET /api/sunshine/objects/types/{object_type_key}/permissions GET /api/sunshine/relationships/types/{relationship_type_key}/permissions

Returns the policies for the specified object type or relationship type.

Allowed For
  • Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/product/permissions \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": {
    "rbac": {
      "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
      }
    },
    "created_at": "2020-07-31T10:09:36Z",
    "updated_at": "2020-07-31T10:09:36Z"
  }
}

Update Policies

PATCH /api/sunshine/objects/types/{object_type_key}/permissions PATCH /api/sunshine/relationships/types/{relationship_type_key}/permissions

Updates the policies for the specified object type or relationship 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. 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
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 statement

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/product/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,
        "read": true,
        "update": true,
        "delete": true
      },
      "agent": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      },
      "end_user": {
        "create": false,
        "read": true,
        "update": false,
        "delete": false
      }
    },
    "rebac": {
      "user_to_many_products": {
        "admin": {
          "read": true,
          "update": true
        },
        "agent": {
          "read": false,
          "update": false
        },
        "end_user": {
          "read": false,
          "update": true
        }
      }
    },
    "created_at": "2020-07-31T10:09:36Z",
    "updated_at": "2020-07-31T10:09:36Z"
  }
}