Protocol buffers API

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

  • CheckRequest

  • CheckResponse

  • 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 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	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

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. <!-- Set this field to true in case your application needs to authorize depending on up to date ACLs, also called a "content-change check".

If set to true the snaptoken field is ignored, the check is evaluated at the latest snapshot (globally consistent) and the response includes a snaptoken for clients to store along with object contents that can be used for subsequent checks of the same content version.

Example use case: - You need to authorize a user to modify/delete some resource and it is unacceptable that if the permission to do that had just been revoked some seconds ago so that the change had not yet been fully replicated to all availability zones. --> | | snaptoken | string | | This field is not implemented yet and has no effect. <!-- Optional. Like reads, a check is always evaluated at a consistent snapshot no earlier than the given snaptoken.

Leave this field blank if you want to evaluate the check based on eventually consistent ACLs, benefiting from very low latency, but possibly slightly stale results.

If the specified token is too old and no longer known, the server falls back as if no snaptoken had been specified.

If not specified the server tries to evaluate the check on the best snapshot version where it is very likely that ACLs had already been replicated to all availability zones. --> | | 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. <!-- The last known snapshot token ONLY specified if the request had not specified a snaptoken, since this performed a "content-change request" and consistently fetched the last known snapshot token.

This field is not set if the request had specified a snaptoken!

If set, clients should cache and use this token for subsequent requests to have minimal latency, but allow slightly stale responses (only some milliseconds or seconds). --> |

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.

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. <!-- Optional. Like reads, a expand is always evaluated at a consistent snapshot no earlier than the given snaptoken.

Leave this field blank if you want to expand based on eventually consistent ACLs, benefiting from very low latency, but possibly slightly stale results.

If the specified token is too old and no longer known, the server falls back as if no snaptoken had been specified.

If not specified the server tries to build the tree on the best snapshot version where it is very likely that ACLs had already been replicated to all availability zones. --> |

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. <!-- Optional. The list of fields to be expanded in the RelationTuple list returned in ListRelationTuplesResponse. Leaving this field unspecified means all fields are expanded.

Available fields: "object", "relation", "subject", "namespace", "subject.id", "subject.namespace", "subject.object", "subject.relation" --> | | snaptoken | string | | This field is not implemented yet and has no effect. <!-- Optional. The snapshot token for this read. --> | | 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.

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.

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 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 is not implemented yet and has no effect. <!-- The list of the new latest snapshot tokens of the affected RelationTuple, with the same index as specified in the relation_tuple_deltas field of the TransactRelationTuplesRequest request.

If the RelationTupleDelta_Action was DELETE the snaptoken is empty at the same index. --> |

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 relation tuples in a single transaction.
DeleteRelationTuples	DeleteRelationTuplesRequest	DeleteRelationTuplesResponse	Deletes relation tuples 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)