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.