package ory.keto.relation_tuples.v1alpha2

Get desktop application:
View/edit binary Protocol Buffers messages

The service that performs authorization checks based on the stored Access Control Lists. This service is part of the [read-APIs](../concepts/25_api-overview.mdx#read-apis).

• rpc Check (CheckRequest, CheckResponse)

  check_service.proto:20

  Performs an authorization check.

  message CheckRequest

  check_service.proto:26

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

  • string namespace = 1

    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.

  • string object = 2

    The related object in this check.

  • string relation = 3

    The relation between the Object and the Subject.

  • optional Subject subject = 4

    The related subject in this check.

  • optional RelationTuple tuple = 8

  • bool latest = 5

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

  • string snaptoken = 6

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

  • int32 max_depth = 7

    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.

  message CheckResponse

  check_service.proto:88

  The response for a CheckService.Check rpc.

  • bool allowed = 1

    Whether the specified subject (id) is related to the requested object. It is false by default if no ACL matches.

  • string snaptoken = 2

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

• rpc BatchCheck (BatchCheckRequest, BatchCheckResponse)

  check_service.proto:21

  message BatchCheckRequest

  check_service.proto:140

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

  • repeated RelationTuple tuples = 1

  • bool latest = 2

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

  • string snaptoken = 3

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

  • int32 max_depth = 4

    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.

  message BatchCheckResponse

  check_service.proto:188

  The response for a CheckService.BatchCheck rpc.

  • repeated CheckResponseWithError results = 1

    The results of the batch check. The order of these results will match the order of the input.

The service that performs subject set expansion based on the stored Access Control Lists. This service is part of the [read-APIs](../concepts/25_api-overview.mdx#read-apis).

• rpc Expand (ExpandRequest, ExpandResponse)

  expand_service.proto:20

  Expands the subject set into a tree of subjects.

  message ExpandRequest

  expand_service.proto:25

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

  • optional Subject subject = 1

    The subject to expand.

  • int32 max_depth = 2

    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.

  • string snaptoken = 3

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

  message ExpandResponse

  expand_service.proto:56

  The response for a ExpandService.Expand RPC.

  • optional SubjectTree tree = 1

    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.

The service to query namespaces. This service is part of the [read-APIs](../concepts/25_api-overview.mdx#read-apis).

• rpc ListNamespaces (ListNamespacesRequest, ListNamespacesResponse)

  namespaces_service.proto:17

  Lists Namespaces

  message ListNamespacesRequest

  namespaces_service.proto:21

  Request for ReadService.ListNamespaces RPC.

  (message has no fields)

  message ListNamespacesResponse

  namespaces_service.proto:23

  • repeated Namespace namespaces = 1

The service to query relationships. This service is part of the [read-APIs](../concepts/25_api-overview.mdx#read-apis).

• rpc ListRelationTuples (ListRelationTuplesRequest, ListRelationTuplesResponse)

  read_service.proto:20

  Lists ACL relationships.

  message ListRelationTuplesRequest

  read_service.proto:25

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

  • optional ListRelationTuplesRequest.Query query = 1

    All query constraints are concatenated with a logical AND operator. The RelationTuple list from ListRelationTuplesResponse is ordered from the newest RelationTuple to the oldest.

  • optional RelationQuery relation_query = 6

  • optional google.protobuf.FieldMask expand_mask = 2

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

  • string snaptoken = 3

    This field is not implemented yet and has no effect. <!-- Optional. The snapshot token for this read. -->

  • int32 page_size = 4

    Optional. The maximum number of RelationTuples to return in the response. Default: 100

  • string page_token = 5

    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.

  message ListRelationTuplesResponse

  read_service.proto:87

  The response of a ReadService.ListRelationTuples RPC.

  • repeated RelationTuple relation_tuples = 1

    The relationships matching the list request.

  • string next_page_token = 2

    The token required to get the next page. If this is the last page, the token will be the empty string.

The service returning the specific Ory Keto instance version. This service is part of the [read-APIs](../concepts/25_api-overview.mdx#read-apis) and [write-APIs](../concepts/25_api-overview.mdx#write-apis).

• rpc GetVersion (GetVersionRequest, GetVersionResponse)

  version.proto:17

  Returns the version of the Ory Keto instance.

  message GetVersionRequest

  version.proto:21

  Request for the VersionService.GetVersion RPC.

  (message has no fields)

  message GetVersionResponse

  version.proto:24

  Response of the VersionService.GetVersion RPC.

  • string version = 1

    The version string of the Ory Keto instance.

The write service to create and delete Access Control Lists. This service is part of the [write-APIs](../concepts/25_api-overview.mdx#write-apis).

• rpc TransactRelationTuples (TransactRelationTuplesRequest, TransactRelationTuplesResponse)

  write_service.proto:19

  Writes one or more relationships in a single transaction.

  message TransactRelationTuplesRequest

  write_service.proto:25

  The request of a WriteService.TransactRelationTuples RPC.

  • repeated RelationTupleDelta relation_tuple_deltas = 1

    The write delta for the relationships operated in one single transaction. Either all actions succeed or no change takes effect on error.

  message TransactRelationTuplesResponse

  write_service.proto:54

  The response of a WriteService.TransactRelationTuples rpc.

  • repeated string snaptokens = 1

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

• rpc DeleteRelationTuples (DeleteRelationTuplesRequest, DeleteRelationTuplesResponse)

  write_service.proto:21

  Deletes relationships based on relation query

  message DeleteRelationTuplesRequest

  write_service.proto:67

  • optional DeleteRelationTuplesRequest.Query query = 1

  • optional RelationQuery relation_query = 2

  message DeleteRelationTuplesResponse

  write_service.proto:85

  (message has no fields)

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

Used in: BatchCheckResponse

• bool allowed = 1

  Whether the specified subject (id) is related to the requested object. It is false by default if no ACL matches.

• string error = 2

  If there was an error checking the tuple, this will contain the error message. If the check was performed successfully, this will be empty.

• string snaptoken = 3

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

The query for deleting relationships

Used in: DeleteRelationTuplesRequest

• string namespace = 1

  Optional. The namespace to query.

• string object = 2

  Optional. The object to query for.

• string relation = 3

  Optional. The relation to query for.

• optional Subject subject = 4

  Optional. The subject to query for.

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

Used in: ListRelationTuplesRequest

• string namespace = 1

  Required. The namespace to query.

• string object = 2

  Optional. The object to query for.

• string relation = 3

  Optional. The relation to query for.

• optional Subject subject = 4

  Optional. The subject to query for.

Used in: ListNamespacesResponse

• string name = 1

Used in: SubjectTree

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

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

Used in: DeleteRelationTuplesRequest, ListRelationTuplesRequest

• optional string namespace = 1

  The namespace this relation tuple lives in.

• optional string object = 2

  The object related by this tuple. It is an object in the namespace of the tuple.

• optional string relation = 3

  The relation between an Object and a Subject.

• optional Subject subject = 4

  The subject related by this tuple. A Subject either represents a concrete subject id or a `SubjectSet` that expands to more Subjects.

RelationTuple defines a relation between an Object and a Subject.

Used in: BatchCheckRequest, CheckRequest, ListRelationTuplesResponse, RelationTupleDelta, SubjectTree

• string namespace = 1

  The namespace this relation tuple lives in.

• string object = 2

  The object related by this tuple. It is an object in the namespace of the tuple.

• string relation = 3

  The relation between an Object and a Subject.

• optional Subject subject = 4

  The subject related by this tuple. A Subject either represents a concrete subject id or a `SubjectSet` that expands to more Subjects.

Write-delta for a TransactRelationTuplesRequest.

Used in: TransactRelationTuplesRequest

• RelationTupleDelta.Action action = 1

  The action to do on the RelationTuple.

• optional RelationTuple relation_tuple = 2

  The target RelationTuple.

Used in: RelationTupleDelta

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

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

Used in: CheckRequest, DeleteRelationTuplesRequest.Query, ExpandRequest, ListRelationTuplesRequest.Query, RelationQuery, RelationTuple, SubjectTree

• oneof ref

  The reference of this abstract subject.

  • string id = 1

    A concrete id of the subject.

  • SubjectSet set = 2

    A subject set that expands to more Subjects. More information are available under [concepts](../concepts/15_subjects.mdx).

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

Used in: Subject

• string namespace = 1

  The namespace of the object and relation referenced in this subject set.

• string object = 2

  The object related by this subject set.

• string relation = 3

  The relation between the object and the subjects.

Used in: ExpandResponse

• NodeType node_type = 1

  The type of the node.

• optional Subject subject = 2

  The subject this node represents. Deprecated: More information is now available in the tuple field.

• optional RelationTuple tuple = 4

  The relation tuple this node represents.

• repeated SubjectTree children = 3

  The children of this node. This is never set if `node_type` == `NODE_TYPE_LEAF`.