How do I check a permission using the API?

[jonlambert]

Hey!

I'm evaluating using Keto at the moment for use in our team.

I understand we can define relationships between entities (Document, Folder, User) and there appears to be a section in the docs that refers to permissions, and how to define them in OPL using the permits attribute.

However, it's not clear at all how I query this using the API.

Taking this example from the docs:

import { Namespace, Context } from "@ory/keto-namespace-types"

class User implements Namespace {}

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

  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)),
  }
}

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

How do I query the view permission? The documentation directs me to the API, which has an endpoint which allows me to "Check a permission", but there doesn't seem to be anything relating to permissions in the arguments to the endpoint:

{
  "namespace": "string",
  "object": "string",
  "relation": "string",
  "subject_id": "string",
  "subject_set": {
    "namespace": "string",
    "object": "string",
    "relation": "string"
  }
}

Am I missing something super obvious? Apologies if so!

[vinckr]

Hello @jonlambert

No worries at all, it's a great question!

In Ory Keto, permissions are modeled as relationships between entities. The permits attribute in your OPL code defines these permissions as relationships. For example, the view permission is defined as a relationship where a user is a viewer, editor, or owner of a document, or if the user can view the parent folder.

When you want to check a permission using the Keto API, you're essentially checking if a certain relationship exists. For example, to check if a user has the view permission on a document, you would check if the user is in the viewers, editors, or owners relationship with the document, or if the user can view the parent folder.

The API endpoint you mentioned, GET /relation-tuples/check, is used to check these relationships. The parameters namespace, object, relation, and subject_id or subject_set are used to specify the relationship you want to check.

Here's how you might use it to check the view permission:

• namespace: This would be the namespace of the document, as defined in your OPL code.
• object: This would be the ID of the document you want to check the permission for.
• relation: This would be the relationship you want to check, such as viewers, editors, or owners.
• subject_id: This would be the ID of the user you want to check the permission for.

You would make a separate API request for each relationship you want to check. If any of the requests return true, then the user has the view permission.

For more details on how to use the API, you can refer to the Keto API Reference.

I hope this helps! Let me know if you have any other questions.

[tjoekbezoer]

If I understand correctly, this is more about how to invoke the method view defined in the permits property. I can see it being mentioned here (https://www.ory.sh/docs/guides/permissions/overview#transitive-permissions-for-objects-in-the-hierarchy), but that is for the ORY network.

I would be very interested to know how to invoke permits when self hosting.

[tjoekbezoer]

And ofcourse, right after posting I find the answer. I modified a command like ory is allowed User:Henning view File private to keto check User:Henning view File private (where view would be a function defined in a permits property), and it seems to function!

It appears that, in the CLI command signature keto check <subject> <relation> <namespace> <object> [flags], the <relation> part can either be a relation value from a tuple stored in the database, or a permits function from the typescript namespaces definition.

[melezhik]

So, no way to check permission via HTTP API? Only via cli?

[vinckr]

have you had a look at the API docs?
https://www.ory.com/docs/keto/reference/rest-api#tag/permission/operation/checkPermissionOrError

[tjoekbezoer]

I think melizhik has the same need as I have: invoke the view method from the permits property via the API. So instead of using the keto or ory CLI tool, just call an API endpoint to invoke that method. It's this method that then checks individual relations stored in the database.

From what I understand the API can only directly check the database for relations (permissions?), and has no access to the OPL code. Is this correct and if not, how can it be used via the API?

[vinckr]

The CLI is just a wrapper for the API.

Pass the permits function name (e.g. view) as the relation parameter in your check request:
GET /relation-tuples/check?namespace=File&object=private&relation=view&subject_id=User:vinckr
Or POST equivalent.

The Check Permission endpoint evaluates the full OPL model, including permits functions and traversals, not just direct tuples. The max-depth parameter controls traversal depth.

Reference in API docs: https://www.ory.com/docs/keto/reference/rest-api#tag/permission/operation/checkPermission

Let me know if that helps @melezhik @tjoekbezoer

[melezhik]

When you want to check a permission using the Keto API, you're essentially checking if a certain relationship exists. For example, to check if a user has the view permission on a document, you would check if the user is in the viewers, editors, or owners relationship with the document, or if the user can view the parent folder.

This would defeat the idea of abstracting away details of permission (view: (ctx: Context): boolean =>), end user should not know what specific relationships permission consists of and their internal structure, neither they have to check those relationships separately , all the need to do is to check permission as a black box ... So it'd be nice to allow check permissions via HTTP API

[vinckr]

see api docs linked above

[melezhik]

Thanks . It took me some time to realize that as the ory documentation does not clarify that , including the API docs you have mentioned

…

On Fri, Dec 19, 2025 at 8:40 PM Vincent ***@***.***> wrote: The CLI is just a wrapper for the API. Pass the permits function name (e.g. view) as the relation parameter in your check request: GET /relation-tuples/check?namespace=File&object=private&relation=view&subject_id=User:vinckr Or POST equivalent. The Check Permission endpoint evaluates the full OPL model, including permits functions and traversals, not just direct tuples. The max-depth parameter controls traversal depth. Reference in API docs: https://www.ory.com/docs/keto/reference/rest-api#tag/permission/operation/checkPermission Let me know if that helps @melezhik <https://github.com/melezhik> @tjoekbezoer <https://github.com/tjoekbezoer> — Reply to this email directly, view it on GitHub <#1527 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHRHSIHOZAJG325OGC5YIL4CQ2A3AVCNFSM6AAAAACOWVBGFOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMZQGEYDGMY> . You are receiving this because you were mentioned.Message ID: ***@***.***>