Skip to main content
Version: v0.6

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.

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.

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 NameRequest TypeResponse TypeDescription
CheckCheckRequestCheckResponsePerforms an authorization check.

CheckRequest#

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

FieldTypeLabelDescription
namespacestringThe 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.
objectstringThe related object in this check.
relationstringThe relation between the Object and the Subject.
subjectSubjectThe related subject in this check.
latestboolThis field is not implemented yet and has no effect.
snaptokenstringThis field is not implemented yet and has no effect.

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.

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 NameRequest TypeResponse TypeDescription
ExpandExpandRequestExpandResponseExpands the subject set into a tree of subjects.

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. 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.
subjectSubjectThe subject 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.

ory/keto/acl/v1alpha1/read_service.proto#

ReadService#

The service to query relation tuples.

This service is part of the read-APIs.

Method NameRequest TypeResponse TypeDescription
ListRelationTuplesListRelationTuplesRequestListRelationTuplesResponseLists ACL relation tuples.

ListRelationTuplesRequest#

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

FieldTypeLabelDescription
queryListRelationTuplesRequest.QueryAll query constraints are concatenated with a logical AND operator.
The RelationTuple list from ListRelationTuplesResponse is ordered from the newest RelationTuple to the oldest.
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 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
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 relation tuples 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.

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

GetVersionRequest#

Request for the VersionService.GetVersion RPC.

GetVersionResponse#

Response of the VersionService.GetVersion RPC.

FieldTypeLabelDescription
versionstringThe 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 NameRequest TypeResponse TypeDescription
TransactRelationTuplesTransactRelationTuplesRequestTransactRelationTuplesResponseWrites one or more relation tuples in a single transaction.

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

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.
INSERT1Insertion of a new RelationTuple. It is ignored if already existing.
DELETE2Deletion of the RelationTuple. It is ignored if it does not exist.

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)
Last updated on by aeneasr