When calling the

/relation-tuples/check

endpoint in the Ory API, the "relation" parameter is part of the relationship tuple that you're checking. It's not directly a "permit" or "permission" from the permission model, but it is used to determine if a certain permission exists. In Ory, permissions are just another form of relations. Therefore, a permission check is a request to check whether a subject has a certain relation to an object, possibly through one or more indirections. For example, you might check if

user1

is a

reader

of

file1

by checking the relation

is users:user1 in readers of files:file1?

. So, while the "relation" parameter isn't directly a "permit" or "permission", it's a crucial part of the process Ory uses to check permissions. For more details, you can refer to the [Ory API Reference](https://www.ory.sh/docs/reference/api) and the [Ory Permissions Overview](https://www.ory.sh/docs/guides/permissions/overview#basic-concepts).

To query the permissions or permits in Ory, you would typically use the Ory API. However, the exact method for querying permissions can depend on the specific setup and configuration of your Ory instance. In the Ory Permission Language (OPL), permissions are essentially TypeScript functions that return a boolean value based on the relationships in Ory Permissions. These functions allow you to define the access control policies for your application. Here's an example of how you might define permissions in OPL:

typescript import { Namespace, Context } from "@ory/keto-namespace-types"      class User implements Namespace {}      class Document implements Namespace {    // All relationships for a single document.    related: {    editors: User[]    viewers: User[]    }       // The permissions derived from the relationships and context.    permits = {    // A permission is a function that takes the context and returns a boolean. It can reference `this.related` and `this.permits`.    write: (ctx: Context): boolean => this.related.editors.includes(ctx.subject),    read: (ctx: Context): boolean => this.permits.write(ctx) || this.related.viewers.includes(ctx.subject),    }   }

In this example, the

write

and

read

functions are permissions. You can query these permissions by checking if a certain subject has these permissions for a certain object. For more details on how to work with permissions in Ory, you can refer to the [Ory Permissions Guide](https://www.ory.sh/docs/guides/permissions/overview) and the [Ory Permission Language documentation](https://www.ory.sh/docs/keto#ory-permission-language).

In the context of Ory, a relationship, a relation, and a relation tuple are all related concepts used to manage access control and permissions. 1. Relationship: This is the underlying datatype of Ory Permissions. They encode relations between objects (the resources that you want to manage) and subjects (the people or things that want to access these resources). A relationship is associated with a namespace where its relation has to be defined and configured. You can think of relationships as edges in a graph. For example,

User:user1 is in members of Group:group1

is a simple relationship. 2. Relation: This is a part of a relationship. In the example above,

members

is the relation. It defines the type of relationship between the subject and the object. 3. Relation Tuple: This is a more formal term for a relationship. It consists of a namespace, an object, a relation, and a subject. It's a way to represent a relationship in a structured format. For example,

Group:group1#members@User:user1

is a relation tuple. For more details, you can refer to the [Ory Documentation](https://www.ory.sh/docs/keto/concepts/relation-tuples).

In the context of Ory's permission model, "related" and "permits" are properties of a class in the Ory Permission Language (OPL), which is a subset of TypeScript. 1. related: This property is used to define the relationships that an object has with other objects. These relationships are used to determine permissions. For example, a

Document

object might have relationships with

User

objects that are

owners

,

editors

, or

viewers

of the document.

typescript class Document implements Namespace {    related: {    owners: User[]    editors: User[]    viewers: User[]    parents: Folder[]    }   }

2. permits: This property is used to define the permissions that an object has. These permissions are essentially TypeScript functions that return a boolean value based on the relationships in Ory Permissions. For example, a

Document

object might have

view

,

edit

,

delete

, and

share

permissions.

typescript class Document implements Namespace {    permits = {    view: (ctx: Context): boolean =>    this.related.viewers.includes(ctx.subject) ||    this.related.editors.includes(ctx.subject) ||    this.related.owners.includes(ctx.subject) ||    this.related.parents.traverse((parent) => parent.permits.view(ctx)),    }   }

In this example, the

view

permission checks if the subject (the user trying to access the document) is a viewer, editor, or owner of the document, or if they can view the parent folder. For more details, you can refer to the [Ory Documentation](https://www.ory.sh/docs/keto/modeling/create-permission-model#define-permissions-in-the-opl).

In Ory's permission model, you don't directly declare that a given subject_id is a

User

. Instead, you define relationships between subjects and objects. The subject_id is an identifier for a subject, and it's used when defining these relationships. For example, you might define a relationship where a user with the subject_id

user1

is an owner of a document:

typescript class Document implements Namespace {    related: {    owners: ['user1']    }   }

In this example,

user1

is implicitly a

User

because they're included in the

owners

relationship for a

Document

. The subject_id can be any string, and the application must map its resources to a constant, unique identifiers. Ory recommends using UUIDs as they provide a high entropy and therefore are unique identifiers. However, you can also use URLs or opaque tokens as identifiers. Subjects are considered equal when their string representation is equal. For more details, you can refer to the [Ory Documentation](https://www.ory.sh/docs/keto/concepts/subjects).