--- title: "Stratus Permissions" url: https://docs.catalyst.zoho.com/en/cloud-scale/help/stratus/stratus-permissions/ description: "Stratus is a robust cloud storage solution powered by Catalyst. You can store data of any format type in the form of buckets and objects." last_updated: 2026-09-08T11:07:33Z service: Cloud Scale type: general related_links: - name: "Create a Bucket" url: /en/cloud-scale/help/stratus/buckets/create-bucket/ - name: "Java SDK" url: /en/sdk/java/v1/cloud-scale/stratus/overview/ - name: "JavaScript SDK" url: /en/sdk/javascript/v1/cloudscale/stratus/overview/ - name: "Python SDK" url: /en/sdk/python/v1/cloud-scale/stratus/overview/ - name: "iOS SDK" url: /en/sdk/ios/v2/cloud-scale/stratus/overview/ - name: "Android SDK" url: /en/sdk/android/v2/cloud-scale/stratus/overview/ - name: "Flutter SDK" url: /en/sdk/flutter/v2/cloud-scale/stratus/overview/ - name: "REST API" url: /en/api/code-reference/cloud-scale/stratus/get-all-buckets/#GetAllBuckets --- # Stratus Permissions ### Default Permission Template You can create a bucket with one of two types of default permission templates. ![catalyst_stratus_name_bucket](https://catalyst-docs-development.zohostratus.in/images/help/stratus/catalyst_stratus_name_bucket.webp) * **Authenticated Permission Template**: A bucket created using this default permission template will dictate that all the objects of your bucket can only be accessed by users that are authenticated on the client portal of your application. * **Public Permission Template**: A bucket created using this default permission template will allow any end-user on the internet to access the objects of your bucket without any authorization requirement. > **Note:** * Both the permission templates are default types that you have to select while you [create your bucket](https://docs.catalyst.zoho.com/en/cloud-scale/help/stratus/buckets/create-bucket/). These templates are editable, and you can also edit the permissions of individual objects stored in your bucket. * The permissions that are configured are only applicable to project users and not collaborators. * These permissions are meant to define the access level of end-users and not *Collaborators* or *Administrators*. You can define Collaborator's access level in the [Profiles & Permissions](https://docs.catalyst.zoho.com/en/getting-started/set-up-a-catalyst-project/profiles-and-permissions/) section. * Regardless of the permission template you have chosen, **upload** actions in the bucket can only be performed by **authenticated users**. ### Custom Permissions When you create a bucket, you are mandated to choose a default permission template- **Authenticated**, or **Public**. Based on your choice, a default permission template will be loaded, and your bucket will be created. In addition to this, regardless of the permission template you had chosen, you can **define the permissions of every individual object** or sub-directory as a whole using simple JSON code. ![catalyst_stratus_permisions_updating](https://catalyst-docs-development.zohostratus.in/images/help/stratus/catalyst_stratus_permisions_updating.webp) The default permission templates that will be loaded based on your choice are shown below: #### Default Authenticated Permission Template **Authenticated Permission Template** ```json { "rules": [ { "rule_id": "AuthenticatedBucket_Rule1", "condition": { "user": { "auth_type": "authenticated", "zuid": "*" } }, "allowed_actions": [ "GetObject" ], "paths": [ "vendorstats::/*" ], "effect": "allow" } ], "version": "v1" } ``` #### Default Public Permission Template **Authenticated Permission Template** ```json { "rules": [ { "rule_id": "PublicBucket", "condition": { "user": { "auth_type": "public" } }, "actions": [ "GetObject" ], "paths": [ "zylker-bucket-pubs::/*" ], "effect": "allow" } ], "version": "v1" } ``` To effectively edit both the permission templates and employ custom permissions, you need to familiarize yourself with the following JSON keys and their purpose:
JSON Key Name Purpose
`rules`
  • This is the JSON key where you configure your permissions
  • This key will contain all the rules you define for the objects present in the bucket
`rule_id`
  • This is a string that will contain the name of the rule you are going to define.
  • You need to name the rule in a manner you can uniquely identify it.
`effect`
  • This is a key where you can only enter one of two values: **allow** or **deny**
  • Based on the value, the rule will be to *allow* a specific user or users to perform an action, or to *deny* a specific user or users to deny an action.
  • The following behaviour is to be expected when you receive an access request that satisfies conditions present in more than one configured permission statement
    • Even if one matching statement has the effect as **deny** then the `deny` will override all **allow** statements.
    • For an **allow** effect to take place, then **at least one** statement with the matching condition should have its effect as `allow` and none of the statements should have effect as **deny**.
`allowed_actions`
  • This is a key to define the actions that can be performed on the object by the user.
  • The allowed actions are:
    • `GetObject`: To fetch the object data
    • `PutObject`: To create, write and update object data
    • `DeleteObject`: To delete object data
`paths`
  • This key will define the location path of an object.
  • You will be providing this value in standard file path format. The value needs to be provided as an array.
  • To denote **all the objects** present in a subdirectory or a bucket, you can use the asterisk '*' special character.
  • You can also use Dynamic Variables; `X_ZUID` and `X_ORGID` to define the path. These dynamic variables will hold the value of the **UserID**, and **OrgID** respectively. So, to use these dynamic variables you need to have defined your directories and objects with actual **UserID** and **OrgID** names. Please visit [this section](https://docs.catalyst.zoho.com/en/cloud-scale/help/stratus/stratus-permissions/#dynamic-variables) to learn more about defining your object path using Dynamic Variables.
`condition` This JSON key will define the conditions under which the actions need to occur.
`user` This JSON key will be used in the condition key to specify which user, or set of users, does the condition that is being defined apply to.
  • Will contain two other json keys: `auth_type` and `zuid`.
  • You can define the type of user using the `auth_type` json key
  • The `auth_type` will contain a default value when you create the bucket using a default permission template
  • The `auth_type` json key can only contain two values: "`public`" or "`authenticated`".
  • The `zuid` json key will be used to determine which users do the conditions apply to.
  • `zuid` can contain the special character asterisk "*" to mean all ZUIDs qualify for the condition, or can contain an array of ZUIDs to specify which users alone do the conditions apply to.
  • `org_details` is a JSON key that will accept a JSON object. The JSON object will be defined as a JSON key value pair, with the key as `zaaid`, and the value as an array of `zuid values`.
> **Note:** You can determine access based on user IDs either using `zuid values` JSON key-value pair or `org_details` JSON. You cannot use both to define user access.
`Operators` These are JSON keys that will help you in defining cases for the conditions to apply or not apply.
`string_equals` Dictate actions that need to occur if the string values are equal.
`string_not_equals` Define actions that need to occur if the string value does not match.
`string_equals_ignore_case` Define actions where the string value can match regardless of the case (upper/lower) that is used.
`string_not_equals_ignore_case` Define actions that need to occur if the string values do not match regardless of the case that is used.
`string_like` If part of the string value matches with the key you provide, then actions can be performed on the object.
`string_not_like` If part of the string value does not match with the key you provide, then actions can be performed on the object.
`ip_address` Define an action if the source of the request comes from a particular IP or IPs that you are allowing.
`not_ip_address` Define actions that should occur if the source of the request comes from IP or IPs that you are particularly halting.
`Condition Keys`
`referrer` This JSON key will contain the value of the complete URL where the action was requested. The value needs to be provided as an array. For example, let's say you have created a microservice and you have hosted it on [Catalyst AppSail](https://docs.catalyst.zoho.com/en/serverless/help/appsail/introduction/). The value of referrer will be the complete URL of this microservice, and the permission will be defined for actions pertaining to this microservice alone. This key will be used for the following operators:
  • `string_equals`
  • `string_not_equals`
  • `string_equals_ignore_case`
  • `string_not_equals_ignore_case`
  • `string_like`
  • `string_not_like`
`user_agent` This JSON key will contain the value of the source from which the request has been made. The value needs to be provided as an array. Whether the source of the request is an API, from a browser, or so on. This key will be used for the following operators:
  • `string_equals`
  • `string_not_equals`
  • `string_equals_ignore_case`
  • `string_not_equals_ignore_case`
  • `string_like`
  • `string_not_like`
`source_ip` This JSON key will contain the value of only publicly listed IP addresses. The value needs to be provided as an array. It will help you in defining a permission that allows, or denies actions from a particular IP. This key will be used for the following operators:
  • `ip_address`
  • `not_ip_address`
`version`
  • States the version of the permission template, and will hold the current version value - `v1`.
  • We strongly urge that you do not change the value of this key.
> **Note:** Ensure that you are using the **exact names for JSON keys** to define your permissions. ### Dynamic Variables You can use dynamic variables to define the object path while configuring permissions. During runtime, these variables will hold relevant values that define the path of the object. In Stratus, you can use the following dynamic variables to define your path: * `X_ZUID`: Will hold actual `UserIDs` during runtime. * `X_ORGID`: Will hold actual `OrgIDs` during runtime. > **Note:** For dynamic variables to work, you will need to create your object path with either `UserIDs` or `OrgIDs`, as the dynamic variables will only hold those values. **Syntax to Create Dynamic Variables** You have to employ the syntax shown below to use dynamic variables: "paths": ["bucket_name::/${var:X_ZUID}/*"] "paths": ["bucket_name::/${var:X_ORGID}/*"] > **Note:** * `paths`: Will hold the value of the path of the object * `bucket_name`: Will hold the value of the name of the bucket **Syntax to use Dynamic Variables** Let's look at the following example, where we define the path of the object using the `X_ZUID` dynamic variable **Define path using the X_ZUID dynamic variable** ```json { "version": "v1", "rules": [ { "rule_id": "Example rule to allow user to access the path which has their ZUID in the path", "condition": { "user": { "auth_type": "authenticated", "zuid": "*" } } } ], "effect": "allow", "allowed_actions": [ "GetObject" ], "paths": [ "bucketName::/${var:X_ZUID}" //Use the X_ORGID variable to define the path using OrgIDs ] } ``` > **Note:** * It is best to use dynamic variables in buckets where the permission template is set as `Authenticated` throughout. ### Examples Illustrating Custom Permissions Now, let's go over a few examples of custom permission templates that can be created to define permissions for an object or objects in a bucket. **Example 1** **Custom Permission Example** ```json { "version" : "v1", "rules" : [ { "rule_id" : "Example rule where all authenticated ZUID users can perform all actions on a particular object", "effect" : "allow", "allowed_actions" : ["GetObject", "PutObject", "DeleteObject"], "paths" : ["bucketName::/user/*", "bucketName::/document/readme.md"], "condition" : [ "user" : { "auth_type" : "authenticated", "zuid" : "*" } ] } ] } ``` From the above snippet, we can understand that: * The permission is configured for an **authenticated permission template** bucket * The permissions will be defined to allow users to perform `GetObject`, `PutObject`, and `DeleteObject` operations. * This permission is only applicable for all of the objects present in the `user/` path and it is applicable only for the `readme.md` object present in `document/` path in the bucket. * The permission is relevant for all *ZUID* present. Putting all this together, we can understand that the above permission is defined for all authenticated users to perform all actions on the **readme.md** object present in the `document/` path, and for all the objects present in the `user/` path. **Example 2** **Custom Permission Example** ```json { "version" : "v1", "rule" : [ { "rule_id" : "Example rule to allow user to access the path which has their ZUID in the path", "effect" : "allow", "allowed_actions" : ["GetObject"], "paths" : ["bucketName::/${var:X_Zuid}"], } ] } ``` From the above snippet, we can understand that: * The path name of the object is defined based on the *ZUID*, whose value will be attained dynamically during runtime. * The particular objects in the path will be allowed to perform the `GetObject` action on the object. Putting all this together, we can understand that the above permission is defined in a manner where a `GetObject` action will on the object whose name has to match the *ZUID* value that will be attained dynamically. **Example 3** **Custom Permission Example** ```json { "version" : "v1", "rule" : [ { "rule_id" : "Example rule to deny specific users from accessing all the objects present in a particular path", "effect" : "deny", "allowed_actions" : ["GetObject", "PutObject", "DeleteObject"], "paths" : ["bucketName::/denyPath/*"], "condition" : { "user" : { "auth_type" : "authenticated", "zuid" : ["123", "456", "789"] } } } ] } ``` From the above snippet, we can understand that: * The permission applies to what particular authenticated users whose *ZUIDs* are listed as an array. * The particular users cannot perform `GetObject`, `PutObject`, or `DeleteObject` actions on all objects present in the bucket. Putting all this together, we can understand that the above permission is defined for authenticated users with the mentioned *ZUIDs*. The mentioned users are not allowed to perform any actions on all objects present in the particular path. **Example 4** **Custom Permission Example** ```json { "version" : "v1", "rule" : [ { "rule_id" : "Example rule employing specific action for specific public paths in the bucket", "effect" : "allow", "allowed_actions" : ["GetObject"], "paths" : ["bucketName::/publicPath/*", "bucketName::/otherPath/otherPublicPath/*"], "condition" : { "user" : { "auth_type" : "public", } } }, { "rule_id" : "Example rule where specifc actions can be performed on objects present in specific authenticated path, and these actions can be performed by all authenticated users", "effect" : "allow", "allowed_actions" : ["GetObject", "PutObject", "DeleteObject"], "paths" : ["bucketName::/authenticatedUser/*", "bucketPath::/otherProtectedPath/*"], "condition" : { "user" : { "auth_type" : "authenticated", "zuid" : "*" } } } ] } ``` From the above snippet, we can understand that: * Two rules are being defined for this bucket. Specific paths in the bucket are listed as **public**, and specific paths in the bucket can only be accessed by **authenticated** users. * `GetObject` is the only action that can be performed on objects that fall under **public path**. However, for the objects that are in the **authenticated path**, and can be accessed by only *authenticated users*, the actions that are allowed to be performed on the authenticated path are `GetObject`, `PutObject`, and `DeleteObject`. Putting all this together, we can comprehend that the above permission is defined by two rules. The first rule defines a permission for a path, where all the objects present in the path can be accessed by anyone as it is *public*. `GetObject` only action that can be performed on the objects in the public path. In the second rule, all *authenticated users* can perform `GetObject`, `PutObject`, and `DeleteObject` actions on all objects listed in the *authenticated path*. **Example 5** **Custom Permission Example** ```json { "version" : "v1", "rules" : [ { "rule_id" : "RuleNumber1", "effect" : "allow", "allowed_actions" : ["GetObject", "PutObject"], "paths" : ["bucketname::/protectedpath/*"], "condition" : { "user" : { "auth_type" : "authenticated", "zuid" : "*" }, "string_equal" : { "user_agent" : ["Mozilla/5.0"], "referrer" : ["https://www.example.com", "https://www.example.com/get_user/"] }, "ip_address" : { "source_ip" : ["121.67.8.1"] } } }, { "rule_id" : "RuleNumber2", "effect" : "deny", "allowed_actions" : ["GetObject"], "paths" : ["bucketname::/denypath/*"], "condition" : { "user" : { "auth_type" : "authenticated" }, "string_like" : { "user_agent" : ["PostmanRuntime/7.39.0"] } } }, { "rule_id" : "RuleNumber3", "effect" : "allow", "allowed_actions" : ["PutObject"], "paths" : ["bucketname::/uploadhere/*"], "condition" : { "user" : { "auth_type" : "authenticated", "org_details" : { "zaaid" : ["12096000001275047", "12096000001278879"] } }, "not_ip_address" : { "source_ip" : ["122.23.44.19"] } } } ] } ``` From the above snippet, we can understand that three rules have been defined- `RuleNumber1`, `RuleNumber2`, and `RuleNumber3`. - `RuleNumber1` - Object access is only possible if the IP addresses of the system that are attempting access match the values listed in `source_ip` in the `ip_address` JSON. - Object access is only possible by users whose `zaaid` (*User IDs*) matches the ones listed in the `org_details` JSON. - Object access is only possible if the access attempt is made by a Mozilla browser from the web, and only if the access request originates from the mentioned `referrers`. - The rule is defined for all **authenticated users**. - If the access request satisfies all the above mentioned conditions, then only `GetObject` and `PutObject` actions are permitted to occur in the defined path. - `RuleNumber2` - The rule is defined for an authenticated user that attempts an access request with `user_agent` is **Postman** (request was made using [Postman API platform](https://www.postman.com/)). - In the defined path, such a user will be denied access to perform `GetObject` operation. - `RuleNumber3` - The rule is defined in a manner where it is applicable, if the request was made from any IP address except the one mentioned in `source_ip` in the `not_ip_address` JSON. - The rule is applicable for only **authenticated users** and specifically to the users whose `zaaid` are defined in `org_details` JSON. - If the user attempts an access request satisfying all the above mentioned conditions, then they are allowed to perform a `PutObject` in the defined path. ### Configure Custom Permissions for Objects Stored in a Bucket To set custom permissions: 1. Select the required bucket from the list. ![catalyst_stratus_permissions_selectiomn_button](https://catalyst-docs-development.zohostratus.in/images/help/stratus/catalyst_stratus_permissions_selectiomn_button.webp) 2. You will be directed to the *Bucket Permissions* tab. Click **Edit Permission**. ![catalyst_stratus_buckets_permissions_section_tab](https://catalyst-docs-development.zohostratus.in/images/help/stratus/catalyst_stratus_buckets_permissions_section_tab.webp) 3. Edit the permissions according to your requirements, then click **Update** to confirm your changes. ![catalyst_stratus_permisions_updating](https://catalyst-docs-development.zohostratus.in/images/help/stratus/catalyst_stratus_permisions_updating.webp) The permissions will be applied according to your configurations. > **Note:** Refer to this [help documentation](https://docs.catalyst.zoho.com/en/cloud-scale/help/stratus/stratus-permissions/#custom-permissions) to learn more about custom permissions.