Skip to main content

Protocol Documentation

Table of Contents

Top

ory/keto/opl/v1alpha1/syntax_service.proto

CheckRequest

FieldTypeLabelDescription
contentbytes

CheckResponse

FieldTypeLabelDescription
parse_errorsParseErrorrepeated

ParseError

FieldTypeLabelDescription
messagestring
startSourcePosition
endSourcePosition

SourcePosition

FieldTypeLabelDescription
lineuint32
columnuint32

SyntaxService

The service that checks the syntax of an OPL file.

Method NameRequest TypeResponse TypeDescription
CheckCheckRequestCheckResponsePerforms 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
FieldTypeLabelDescription
namespacestringoptionalThe namespace this relation tuple lives in.
objectstringoptionalThe object related by this tuple.
It is an object in the namespace of the tuple.
relationstringoptionalThe relation between an Object and a Subject.
subjectSubjectoptionalThe 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.

FieldTypeLabelDescription
namespacestringThe namespace this relation tuple lives in.
objectstringThe object related by this tuple.
It is an object in the namespace of the tuple.
relationstringThe relation between an Object and a Subject.
subjectSubjectThe 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.

FieldTypeLabelDescription
idstringA concrete id of the subject.
setSubjectSetA 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.

FieldTypeLabelDescription
namespacestringThe namespace of the object and relation
referenced in this subject set.
objectstringThe object related by this subject set.
relationstringThe 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.

FieldTypeLabelDescription
tuplesRelationTuplerepeated
latestboolThis field is not implemented yet and has no effect.
snaptokenstringThis field is not implemented yet and has no effect.
max_depthint32The 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.

FieldTypeLabelDescription
resultsCheckResponseWithErrorrepeatedThe 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.

FieldTypeLabelDescription
namespacestringDeprecated. 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.
objectstringDeprecated. The related object in this check.
relationstringDeprecated. The relation between the Object and the Subject.
subjectSubjectDeprecated. The related subject in this check.
tupleRelationTuple
latestboolThis field is not implemented yet and has no effect.
snaptokenstringThis field is not implemented yet and has no effect.
max_depthint32The 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.

FieldTypeLabelDescription
allowedboolWhether the specified subject (id)
is related to the requested object.

It is false by default if no ACL matches.
snaptokenstringThis field is not implemented yet and has no effect.

CheckResponseWithError

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

FieldTypeLabelDescription
allowedboolWhether the specified subject (id)
is related to the requested object.

It is false by default if no ACL matches.
errorstringIf there was an error checking the tuple,
this will contain the error message.

If the check was performed successfully, this will be empty.
snaptokenstringThis 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 NameRequest TypeResponse TypeDescription
CheckCheckRequestCheckResponsePerforms an authorization check.
BatchCheckBatchCheckRequestBatchCheckResponse

Top

ory/keto/relation_tuples/v1alpha2/expand_service.proto

ExpandRequest

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

FieldTypeLabelDescription
subjectSubjectThe subject to expand.
max_depthint32The 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.
snaptokenstringThis field is not implemented yet and has no effect.

ExpandResponse

The response for a ExpandService.Expand RPC.

FieldTypeLabelDescription
treeSubjectTreeThe 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

FieldTypeLabelDescription
node_typeNodeTypeThe type of the node.
subjectSubjectDeprecated. The subject this node represents.
Deprecated: More information is now available in the tuple field.
tupleRelationTupleThe relation tuple this node represents.
childrenSubjectTreerepeatedThe children of this node.

This is never set if node_type == NODE_TYPE_LEAF.

NodeType

NameNumberDescription
NODE_TYPE_UNSPECIFIED0
NODE_TYPE_UNION1This node expands to a union of all children.
NODE_TYPE_EXCLUSION2Not implemented yet.
NODE_TYPE_INTERSECTION3Not implemented yet.
NODE_TYPE_LEAF4This 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 NameRequest TypeResponse TypeDescription
ExpandExpandRequestExpandResponseExpands the subject set into a tree of subjects.

Top

ory/keto/relation_tuples/v1alpha2/namespaces_service.proto

ListNamespacesRequest

Request for ReadService.ListNamespaces RPC.

ListNamespacesResponse

FieldTypeLabelDescription
namespacesNamespacerepeated

Namespace

FieldTypeLabelDescription
namestring

NamespacesService

The service to query namespaces.

This service is part of the read-APIs.

Method NameRequest TypeResponse TypeDescription
ListNamespacesListNamespacesRequestListNamespacesResponseLists 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.

FieldTypeLabelDescription
queryListRelationTuplesRequest.QueryDeprecated. 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_queryRelationQuery
expand_maskgoogle.protobuf.FieldMaskThis field is not implemented yet and has no effect.
snaptokenstringThis field is not implemented yet and has no effect.
page_sizeint32Optional. The maximum number of
RelationTuples to return in the response.

Default: 100
page_tokenstringOptional. 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
FieldTypeLabelDescription
namespacestringRequired. The namespace to query.
objectstringOptional. The object to query for.
relationstringOptional. The relation to query for.
subjectSubjectOptional. The subject to query for.

ListRelationTuplesResponse

The response of a ReadService.ListRelationTuples RPC.

FieldTypeLabelDescription
relation_tuplesRelationTuplerepeatedThe relationships matching the list request.
next_page_tokenstringThe 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 NameRequest TypeResponse TypeDescription
ListRelationTuplesListRelationTuplesRequestListRelationTuplesResponseLists ACL relationships.

Top

ory/keto/relation_tuples/v1alpha2/version.proto

GetVersionRequest

Request for the VersionService.GetVersion RPC.

GetVersionResponse

Response of the VersionService.GetVersion RPC.

FieldTypeLabelDescription
versionstringThe 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 NameRequest TypeResponse TypeDescription
GetVersionGetVersionRequestGetVersionResponseReturns the version of the Ory Keto instance.

Top

ory/keto/relation_tuples/v1alpha2/write_service.proto

DeleteRelationTuplesRequest

FieldTypeLabelDescription
queryDeleteRelationTuplesRequest.QueryDeprecated.
relation_queryRelationQuery

DeleteRelationTuplesRequest.Query

The query for deleting relationships

FieldTypeLabelDescription
namespacestringOptional. The namespace to query.
objectstringOptional. The object to query for.
relationstringOptional. The relation to query for.
subjectSubjectOptional. The subject to query for.

DeleteRelationTuplesResponse

RelationTupleDelta

Write-delta for a TransactRelationTuplesRequest.

FieldTypeLabelDescription
actionRelationTupleDelta.ActionThe action to do on the RelationTuple.
relation_tupleRelationTupleThe target RelationTuple.

TransactRelationTuplesRequest

The request of a WriteService.TransactRelationTuples RPC.

FieldTypeLabelDescription
relation_tuple_deltasRelationTupleDeltarepeatedThe 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.

FieldTypeLabelDescription
snaptokensstringrepeatedThis field is not implemented yet and has no effect.

RelationTupleDelta.Action

NameNumberDescription
ACTION_UNSPECIFIED0Unspecified.
The TransactRelationTuples RPC ignores this
RelationTupleDelta if an action was unspecified.
ACTION_INSERT1Insertion of a new RelationTuple.
It is ignored if already existing.
ACTION_DELETE2Deletion 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 NameRequest TypeResponse TypeDescription
TransactRelationTuplesTransactRelationTuplesRequestTransactRelationTuplesResponseWrites one or more relationships in a single transaction.
DeleteRelationTuplesDeleteRelationTuplesRequestDeleteRelationTuplesResponseDeletes relationships based on relation query

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)