Skip to main content

API overview

This page gives an overview of Ory Permissions APIs including common use cases.

All APIs are available to gRPC and REST clients, although feature parity isn't guaranteed. Ory follows gRPC and REST best practices and design guidelines, which can cause the APIs offer slightly different interfaces and capabilities.

Read APIs​

List relationships​

This API allows you to query relationships by providing a partial relationship. It can be used to:

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

Check relationships​

The Check API allows you to check whether a subject has a relation on an object. This API resolves subject sets and relationships.

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.

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 relationships 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.

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

Write APIs​

Change relationships​

The Write APIs offer multiple ways to insert and delete relationships. 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