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.
This API allows you to query relationships by providing a partial relationship. It can be used to:
- list objects a user has access to
- list users who have a specific role
- list users who are members of a specific group
- audit permissions in the system
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.
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:
- List who has access to an object
- Determine why someone has access to an object
- Audit permissions in the system
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.
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