4 mins read

Configuring Permissions for Application Access Control

Find out how to set up access to resources and applications with Permission Systems on your Cloudentity tenant. With it, you create a robust schema augmented with relations and permissions to build a fine-grained system that facilitate checking who has access to what objects and what actions are allowed either to an individual user or a user group.

Create a Permission System

  1. Select Permission Systems on the left navigation panel.

    Click the Settings button and select Permission Systems in the drop-down, if you’re within a workspace.

  2. Click + CREATE SYSTEM in the Permission Systems section.

  3. Set the permission system name, description, and prefix . Click Create.


    By default, the prefix combines your tenant name and the name of your permission system. You can modify the prefix at the permission system creation step. Once the permission system is all set, use the prefix value exactly as you see it under the Configuration tab.

  4. Click your newly created permission system tile. Proceed with the steps specified under the Quickstart tab.

Create a Token

  1. Go to the Tokens tab. Click + ADD TOKEN.

  2. Set the token name and description. Click Create.

    Save Your Token API Key

    The API key value is displayed only once, at the token creation step.

    An API key is automatically generated for your new token. The API key is required for further work with your permission system. Copy the API key. Make sure it’s stored securely.

    At any time, you can generate a new token along with the matching API key. Any subsequent token usage requires switching the zed context. Read Further Steps for details.

Apply a Schema

  1. Copy the schema value.

  2. Go to the Schema tab. Paste the schema copied to the code block. Save your changes.

The template given below illustrates a basic schema to be created from scratch. It includes a subject type = user, a resource type = post, the relations, and permissions. Based on the schema, you’ll add and handle actual subjects and resources to the permission system data table.

You can modify the schema according to your requirements, replacing the $-variables with the actual values.

Use the schema language reference for advanced guidance.

Schema Template

definition $PREFIX/user {}

definition $PREFIX/post {
   relation reader: $PREFIX/user
   relation writer: $PREFIX/user

   permission read = reader + writer
   permission write = writer

Store Relationships

Now you can record the actual values to your permission system data table.

Call the endpoint provided in the Store relationships block. Cloudentity generates the request_url value for your tenant with the $PERMISSION_SYSTEM_ID retrieved.

The resource and subject IDs are your target resources (for example, post, organization, or whatever else) and actual users or applications to whom you grant permissions.

The WriteRelationsResponse response includes the revision value. Save this value for the Check Permissions step and for further operations with your permission system.

Store Relationships CURL Template

curl -X POST "https://$TENANT_ID.$$TENANT_ID/system/systems/$PERMISSION_SYSTEM_ID/relationships" \
-H "X-Api-Key: $API_KEY" \
-d '{ "updates": [{
"operation": "upsert",
"relation": "writer",
"resource_id": "$RESOURCE_ID",
"resource_type": "$PREFIX/post",
"subject_id": "$SUBJECT_ID",
"subject_type": "$PREFIX/user"
}] }'

Check Permissions

Once the schema is applied and relationships stored, you can check permissions. For this, make a test call with the cURL provided in the Check permissions Quickstart block.

Or use the template below, replacing the $-variables with your custom values, if any, and calling your response_url.

Check Permissions CURL Template

curl -X POST "https://$TENANT_ID.$$TENANT_ID/system/systems/$PERMISSION_SYSTEM_ID/check" \
   -H "X-Api-Key: $API_KEY" \
   -d '{
       "revision": "$REVISION_VALUE",
       "permission": "read",
       "resource_id": "$RESOURCE_ID",
       "resource_type": "$PREFIX/post",
       "subject_id": "$SUBJECT_ID",
       "subject_type": "$PREFIX/user"

Variable Reference

Further Steps

Once your permission system is all set, it’s available for further management. With Cloudentity permission system APIs cover the full range of operations to handle permissions from creation through checks to removal, including:

You can also generate a new token with the matching API key under the Tokens tab in your permission system settings. To use the new token, switch zed context: run zed context set acp grpc.$ $API_KEY.

Cloudentity Permission System uses SpiceDB as authorization data storage. SpiceDB SDK languages are also supported. When you’re employing SpiceDB SDK, use grpc.$

The Check it out blog post explains how permission systems work in detail.

Updated: Sep 28, 2023