Protocol buffers API

The API is divided into the read APIs and write APIs. Each service is annotated with the API it belongs to.

ory/keto/acl/v1alpha1/acl.proto

RelationTuple

RelationTuple defines a relation between an Object and a Subject.

Field	Type	Label	Description
namespace	string		The namespace this relation tuple lives in.
object	string		The object related by this tuple. It's an object in the namespace of the tuple.
relation	string		The relation between an Object and a Subject.
subject	Subject		The subject related by this tuple. A Subject either represents a concrete subject id or a SubjectSet that expands to more Subjects.

Subject

Subject is either a concrete subject id or a SubjectSet expanding to more Subjects.

Field	Type	Label	Description
id	string		A concrete id of the subject.
set	SubjectSet		A subject set that expands to more Subjects. More information are available under concepts.

SubjectSet

SubjectSet refers to all subjects who have the same relation on an object.

Field	Type	Label	Description
namespace	string		The namespace of the object and relation referenced in this subject set.
object	string		The object related by this subject set.
relation	string		The relation between the object and the subjects.

ory/keto/acl/v1alpha1/check_service.proto

CheckService

The service that performs authorization checks based on the stored Access Control Lists.

This service is part of the read-APIs.

Method Name	Request Type	Response Type	Description
Check	CheckRequest	CheckResponse	Performs an authorization check.

CheckRequest

The request for a CheckService.Check RPC. Checks whether a specific subject is related to an object.

Field	Type	Label	Description
namespace	string		The namespace to evaluate the check. Note: If you use the expand-API and the check evaluates a RelationTuple specifying a SubjectSet as subject or due to a rewrite rule in a namespace config this check request may involve other namespaces automatically.
object	string		The related object in this check.
relation	string		The relation between the Object and the Subject.
subject	Subject		The related subject in this check.
latest	bool		This field isn't implemented yet and has no effect.
snaptoken	string		This field isn't implemented yet and has no effect.
max_depth	int32		The maximum depth to search for a relation. If the value is less than 1 or greater than the global max-depth then the global max-depth will be used instead.

CheckResponse

The response for a CheckService.Check rpc.

Field	Type	Label	Description
allowed	bool		Whether the specified subject (id) is related to the requested object. It's false by default if no ACL matches.
snaptoken	string		This field isn't implemented yet and has no effect.

ory/keto/acl/v1alpha1/expand_service.proto

ExpandService

The service that performs subject set expansion based on the stored Access Control Lists.

This service is part of the read-APIs.

Method Name	Request Type	Response Type	Description
Expand	ExpandRequest	ExpandResponse	Expands the subject set into a tree of subjects.

ExpandRequest

The request for an ExpandService.Expand RPC. Expands the given subject set.

Field	Type	Label	Description
subject	Subject		The subject to expand.
max_depth	int32		The maximum depth of tree to build. If the value is less than 1 or greater than the global max-depth then the global max-depth will be used instead. It's important to set this parameter to a meaningful value. Ponder how deep you really want to display this.
snaptoken	string		This field isn't implemented yet and has no effect.

ExpandResponse

The response for a ExpandService.Expand RPC.

Field	Type	Label	Description
tree	SubjectTree		The tree the requested subject set expands to. The requested subject set is the subject of the root. This field can be nil in some circumstances.

SubjectTree

Field	Type	Label	Description
node_type	NodeType		The type of the node.
subject	Subject		The subject this node represents.
children	SubjectTree	repeated	The children of this node. This is never set if node_type == NODE_TYPE_LEAF.

NodeType

Name	Number	Description
NODE_TYPE_UNSPECIFIED	0
NODE_TYPE_UNION	1	This node expands to a union of all children.
NODE_TYPE_EXCLUSION	2	Not implemented yet.
NODE_TYPE_INTERSECTION	3	Not implemented yet.
NODE_TYPE_LEAF	4	This node is a leaf and contains no children. Its subject is a SubjectID unless max_depth was reached.

ory/keto/acl/v1alpha1/read_service.proto

ReadService

The service to query relation tuples.

This service is part of the read-APIs.

Method Name	Request Type	Response Type	Description
ListRelationTuples	ListRelationTuplesRequest	ListRelationTuplesResponse	Lists ACL relation tuples.

ListRelationTuplesRequest

Request for ReadService.ListRelationTuples RPC. See ListRelationTuplesRequest_Query for how to filter the query.

Field	Type	Label	Description
query	ListRelationTuplesRequest.Query		All query constraints are concatenated with a logical AND operator. The RelationTuple list from ListRelationTuplesResponse is ordered from the newest RelationTuple to the oldest.
expand_mask	google.protobuf.FieldMask		This field isn't implemented yet and has no effect.
snaptoken	string		This field isn't implemented yet and has no effect.
page_size	int32		Optional. The maximum number of RelationTuples to return in the response. Default: 100
page_token	string		Optional. An opaque pagination token returned from a previous call to ListRelationTuples that indicates where the page should start at. An empty token denotes the first page. All successive pages require the token from the previous page.

ListRelationTuplesRequest.Query

The query for listing relation tuples. Clients can specify any optional field to partially filter for specific relation tuples.

Example use cases (namespace is always required):

• object only: display a list of all permissions referring to a specific object
• relation only: get all groups that have members; get all directories that have content
• object & relation: display all subjects that have a specific permission relation
• subject & relation: display all groups a subject belongs to; display all objects a subject has access to
• object & relation & subject: check whether the relation tuple already exists

Field	Type	Label	Description
namespace	string		Required. The namespace to query.
object	string		Optional. The object to query for.
relation	string		Optional. The relation to query for.
subject	Subject		Optional. The subject to query for.

ListRelationTuplesResponse

The response of a ReadService.ListRelationTuples RPC.

Field	Type	Label	Description
relation_tuples	RelationTuple	repeated	The relation tuples matching the list request.
next_page_token	string		The token required to get the next page. If this is the last page, the token will be the empty string.

ory/keto/acl/v1alpha1/version.proto

VersionService

The service returning the specific Ory Keto instance version.

This service is part of the read-APIs and write-APIs.

Method Name	Request Type	Response Type	Description
GetVersion	GetVersionRequest	GetVersionResponse	Returns the version of the Ory Keto instance.

GetVersionRequest

Request for the VersionService.GetVersion RPC.

GetVersionResponse

Response of the VersionService.GetVersion RPC.

Field	Type	Label	Description
version	string		The version string of the Ory Keto instance.

ory/keto/acl/v1alpha1/write_service.proto

WriteService

The write service to create and delete Access Control Lists.

This service is part of the write-APIs.

Method Name	Request Type	Response Type	Description
TransactRelationTuples	TransactRelationTuplesRequest	TransactRelationTuplesResponse	Writes one or more relation tuples in a single transaction.
DeleteRelationTuples	DeleteRelationTuplesRequest	DeleteRelationTuplesResponse	Deletes relation tuples based on relation query

DeleteRelationTuplesRequest

Field	Type	Label	Description
query	DeleteRelationTuplesRequest.Query

DeleteRelationTuplesRequest.Query

The query for deleting relation tuples

Field	Type	Label	Description
namespace	string		Optional. The namespace to query.
object	string		Optional. The object to query for.
relation	string		Optional. The relation to query for.
subject	Subject		Optional. The subject to query for.

DeleteRelationTuplesResponse

RelationTupleDelta

Write-delta for a TransactRelationTuplesRequest.

Field	Type	Label	Description
action	RelationTupleDelta.Action		The action to do on the RelationTuple.
relation_tuple	RelationTuple		The target RelationTuple.

TransactRelationTuplesRequest

The request of a WriteService.TransactRelationTuples RPC.

Field	Type	Label	Description
relation_tuple_deltas	RelationTupleDelta	repeated	The write delta for the relation tuples operated in one single transaction. Either all actions succeed or no change takes effect on error.

TransactRelationTuplesResponse

The response of a WriteService.TransactRelationTuples rpc.

Field	Type	Label	Description
snaptokens	string	repeated	This field isn't implemented yet and has no effect.

RelationTupleDelta.Action

Name	Number	Description
ACTION_UNSPECIFIED	0	Unspecified. The TransactRelationTuples RPC ignores this RelationTupleDelta if an action was unspecified.
INSERT	1	Insertion of a new RelationTuple. It's ignored if already existing.
DELETE	2	Deletion of the RelationTuple. It's ignored if it doesn't exist.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)