Skip to main content

Define global permission rules using Ory Permission Language

This guide explains how to configure namespaces and relations using the Ory Permission Language.

The example describes a file store. Individual files are organized in a folder hierarchy, and can be accessed by individual users or groups of users. Using the Ory Permission Language you can specify that if a user has access to a folder, the user also has access to all files in that folder.

Setup and Configuration

First, install Keto. Next, create a keto.yaml file with this basic content:


In the namespaces key, you see the line config: file://./namespaces.keto.ts. This needs to point to your namespace configuration in the Ory Permission Language.


Namespace configurations without the Ory Permission Language are still supported by either specifying the namespaces directly or a "naked" URI, e.g. namespaces: file://.namespaces.yaml.

Next, create a file with the namespace configuration:



If you are using a text editor with TypeScript support, you can get extra help when using the Ory Permission Language. Make sure to run npm i @ory/keto-namespaces-types and add a tsconfig.json file with the content:


Starting Ory Keto

After you created both configuration files (keto.yaml and namespaces.keto.ts), run this command to start Ory Keto:

$ keto serve --config ./path/to/keto.yaml

Creating the tuples

Now that Ory Keto is running, create relation tuples using the Keto CLI.

The following relation tuples showcase the namespace configuration. In short, it sets up a "developer" group with two members, and a folder hierarchy. Through the rules in the Ory Permission Language, every member of the "developer" group can access the files in the hierarchy.

You can create additional fine-grained permission rules for certain objects, similar to the "private" file.


To load the file into Ory Keto, run this command:

$ keto relation-tuple create tuples.json

Group developer members patrik
Group developer members User:Patrik
Group developer members User:Henning
Folder keto/ viewers Group:developer#members
File keto/ parents Folder:keto/
Folder keto/src/ parents Folder:keto/
File keto/src/main.go parents Folder:keto/src/
File private owners User:Henning

Checking for permissions

Now, let's check some permissions! Some queries to try:

Transitive permissions for objects in the hierarchy

Patrik can view keto/src/main.go. This file is in the keto/src folder, which is in keto. The keto directory has the "developer" group as its "viewers". Patrik is a member of the "developer" group.

$ keto check User:Patrik view File keto/src/main.go

No transitivity for objects outside the hierarchy

Patrik cannot view the private file, since that file is not part of any folder hierarchy Patrik has access to.

$ keto check User:Patrik view File private

Fine-grained permissions for any object

Henning can both edit and view the private file, since he is an "owner" of it.

$ keto check User:Henning view File private

$ keto check User:Henning edit File private

Further reading

To learn more about the Ory Permission Language, read the specification document.