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.

   Prefix

   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.$REGION_ID.authz.cloudentity.io/api/permissions/$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.$REGION_ID.authz.cloudentity.io/api/permissions/$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

CLICK TO UNFOLD

• $API_KEY: The API key generated for the token you’ve created at the first step. Store it for any further calls.

• $PREFIX: Your permission system prefix set at the permission system creation step. It correlates the schema objects with the permission system.

• $PERMISSION_SYSTEM_ID: Your permission system identifier. You can find it in the response URL parameter generated for your permission system within the Quickstart blocks or in the address bar when you’re on the permission system page.

• $RESOURCE_ID: The resource identifier. It defines what is to be accessed by the subject.

• $SUBJECT_ID: The identifier of the subject. It defines who or what has permissions relating to the target resource.

• $REVISION_VALUE: The revision value you’ve obtained with the WriteRelationsResponse parameter upon the Store Relationships step.

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:

• Lookup resources to get the list of resources that have any subject assigned.

• Lookup subjects to get the list of subjects with access to resources.

• Handle token, including its update when the existing token isn’t available.

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.$REGION_ID.authz.cloudentity.io:443 $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.$REGION_ID.authz.cloudentity.io:443.

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