Protocol Documentation

Table of Contents

• ory/keto/opl/v1alpha1/syntax_service.proto

  • CheckRequest
  • CheckResponse
  • ParseError
  • SourcePosition
  • SyntaxService

• ory/keto/relation_tuples/v1alpha2/relation_tuples.proto

  • RelationQuery
  • RelationTuple
  • Subject
  • SubjectSet

• ory/keto/relation_tuples/v1alpha2/check_service.proto

  • BatchCheckRequest
  • BatchCheckResponse
  • CheckRequest
  • CheckResponse
  • CheckResponseWithError
  • CheckService

• ory/keto/relation_tuples/v1alpha2/expand_service.proto

  • ExpandRequest
  • ExpandResponse
  • SubjectTree
  • NodeType
  • ExpandService

• ory/keto/relation_tuples/v1alpha2/namespaces_service.proto

  • ListNamespacesRequest
  • ListNamespacesResponse
  • Namespace
  • NamespacesService

• ory/keto/relation_tuples/v1alpha2/read_service.proto

  • ListRelationTuplesRequest
  • ListRelationTuplesRequest.Query
  • ListRelationTuplesResponse
  • ReadService

• ory/keto/relation_tuples/v1alpha2/version.proto

  • GetVersionRequest
  • GetVersionResponse
  • VersionService

• ory/keto/relation_tuples/v1alpha2/write_service.proto

  • DeleteRelationTuplesRequest
  • DeleteRelationTuplesRequest.Query
  • DeleteRelationTuplesResponse
  • RelationTupleDelta
  • TransactRelationTuplesRequest
  • TransactRelationTuplesResponse
  • RelationTupleDelta.Action
  • WriteService

• Scalar Value Types

Top

ory/keto/opl/v1alpha1/syntax_service.proto

CheckRequest

Field	Type	Label	Description
content	bytes

CheckResponse

Field	Type	Label	Description
parse_errors	ParseError	repeated

ParseError

Field	Type	Label	Description
message	string
start	SourcePosition
end	SourcePosition

SourcePosition

Field	Type	Label	Description
line	uint32
column	uint32

SyntaxService

The service that checks the syntax of an OPL file.

Method Name	Request Type	Response Type	Description
Check	CheckRequest	CheckResponse	Performs a syntax check request.

Top

ory/keto/relation_tuples/v1alpha2/relation_tuples.proto

RelationQuery

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

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	optional	The namespace this relation tuple lives in.
object	string	optional	The object related by this tuple. It is an object in the namespace of the tuple.
relation	string	optional	The relation between an Object and a Subject.
subject	Subject	optional	The subject related by this tuple. A Subject either represents a concrete subject id or a SubjectSet that expands to more Subjects.

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

Top

ory/keto/relation_tuples/v1alpha2/check_service.proto

BatchCheckRequest

The request for a CheckService.BatchCheck RPC. Checks a batch of relations.

Field	Type	Label	Description
tuples	RelationTuple	repeated
latest	bool		This field is not implemented yet and has no effect.
snaptoken	string		This field is not 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.

BatchCheckResponse

The response for a CheckService.BatchCheck rpc.

Field	Type	Label	Description
results	CheckResponseWithError	repeated	The results of the batch check. The order of these results will match the order of the input.

CheckRequest

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

Field	Type	Label	Description
namespace	string		Deprecated. 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		Deprecated. The related object in this check.
relation	string		Deprecated. The relation between the Object and the Subject.
subject	Subject		Deprecated. The related subject in this check.
tuple	RelationTuple
latest	bool		This field is not implemented yet and has no effect.
snaptoken	string		This field is not 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 is false by default if no ACL matches.
snaptoken	string		This field is not implemented yet and has no effect.

CheckResponseWithError

The response for an individual check in the CheckService.BatchCheck rpc.

Field	Type	Label	Description
allowed	bool		Whether the specified subject (id) is related to the requested object. It is false by default if no ACL matches.
error	string		If there was an error checking the tuple, this will contain the error message. If the check was performed successfully, this will be empty.
snaptoken	string		This field is not implemented yet and has no effect.

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.
BatchCheck	BatchCheckRequest	BatchCheckResponse

Top

ory/keto/relation_tuples/v1alpha2/expand_service.proto

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 is important to set this parameter to a meaningful value. Ponder how deep you really want to display this.
snaptoken	string		This field is not 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		Deprecated. The subject this node represents. Deprecated: More information is now available in the tuple field.
tuple	RelationTuple		The relation tuple 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.

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.

Top

ory/keto/relation_tuples/v1alpha2/namespaces_service.proto

ListNamespacesRequest

Request for ReadService.ListNamespaces RPC.

ListNamespacesResponse

Field	Type	Label	Description
namespaces	Namespace	repeated

Namespace

Field	Type	Label	Description
name	string

NamespacesService

The service to query namespaces.

This service is part of the read-APIs.

Method Name	Request Type	Response Type	Description
ListNamespaces	ListNamespacesRequest	ListNamespacesResponse	Lists Namespaces

Top

ory/keto/relation_tuples/v1alpha2/read_service.proto

ListRelationTuplesRequest

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

Field	Type	Label	Description
query	ListRelationTuplesRequest.Query		Deprecated. All query constraints are concatenated with a logical AND operator. The RelationTuple list from ListRelationTuplesResponse is ordered from the newest RelationTuple to the oldest.
relation_query	RelationQuery
expand_mask	google.protobuf.FieldMask		This field is not implemented yet and has no effect.
snaptoken	string		This field is not 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 relationships. Clients can specify any optional field to partially filter for specific relationships.

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

ReadService

The service to query relationships.

This service is part of the read-APIs.

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

Top

ory/keto/relation_tuples/v1alpha2/version.proto

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.

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.

Top

ory/keto/relation_tuples/v1alpha2/write_service.proto

DeleteRelationTuplesRequest

Field	Type	Label	Description
query	DeleteRelationTuplesRequest.Query		Deprecated.
relation_query	RelationQuery

DeleteRelationTuplesRequest.Query

The query for deleting relationships

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 relationships 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 is not 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.
ACTION_INSERT	1	Insertion of a new RelationTuple. It is ignored if already existing.
ACTION_DELETE	2	Deletion of the RelationTuple. It is ignored if it does not exist.

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 relationships in a single transaction.
DeleteRelationTuples	DeleteRelationTuplesRequest	DeleteRelationTuplesResponse	Deletes relationships based on relation query

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)