Skip to main content

API overview

This page gives an overview over all APIs Ory Keto offers, including common use cases.

The APIs are separated based on privileges into a read and write endpoint. Each endpoint is exposed on a different port, so you can decide how to restrict access. gRPC and REST connections are multiplexed on the same port.

All APIs are available to gRPC and REST clients, although feature parity isn't always given. Because we follow gRPC and REST best practices and design guidelines, the APIs offer slightly different interfaces and capabilities.

Read APIs​

The read-APIs are per default exposed on the TCP port 4466.

List relation tuples​

This API allows you to query relation tuples by providing a partial relation tuple. It can be used to:

For more details, head over to the gRPC API reference or REST API reference.

Check relation tuple​

The check-API allows you to check whether a subject has a relation on an object. This API resolves subject sets and subject set rewrites.

This API is primarily used to check permissions to restrict actions.

A check-request can include the maximum depth of the search tree. If the value is less than 1 or greater than the global max-depth then the global max-depth will be used instead. This is to ensure low latency and limit the resource usage per request. To find out more about Ory Keto's performance, head over to the performance considerations.

For more details, head over to the gRPC API reference or REST API reference.

Expand subject sets​

The expand-API recursively expands a subject set into a tree of subjects. For each subject, the tree assembles the relation tuples including the operands as defined in the namespace configuration. It can be used to:

An expand-request can include the maximum depth of the tree to be returned. If the value is less than 1 or greater than the global max-depth then the global max-depth will be used instead. This is required to ensure low latency and limit the resource usage per request. To find out more about Ory Keto's performance, head over to the performance considerations.

For more details, head over to the gRPC API reference or REST API reference.

Write APIs​

The write-APIs are per default exposed on the TCP port 4467.

Change relation tuples​

The write-APIs offer multiple ways to insert and delete relation tuples. Please head over to the gRPC API reference or REST API reference to read more about the available methods for each client type.

It's preferred to use the transaction based methods over repeatedly calling simple methods for bulk updates. This isn't only because they provide stronger consistency guarantees, but also because the database usually handles a single transaction with a lot of data faster than a lot of small transactions.

The main use cases for the write-APIs are:

  • setting up permissions for a new object
  • sharing an object with another user
  • revoking access to an object
  • transferring relations to an object to another user