📚 API Reference

note

The Authorizer platform supports a standard HTTP/JSON API or grpc APIs backed by protocol-buffers.

Support for the HTTP/JSON API comes from the grpc-gateway package which is a gRPC to JSON proxy generator that follows the standard gRPC and HTTP transcoding spec.

CheckService#

Package: authorizer.accesscontroller.v1alpha1

The service that performs access-control checks based on stored Access Control Lists.

Check#

rpc Check(CheckRequest) CheckResponse

Check performs an access-control check by looking up if a specific subject is related to an object.

ExpandService#

Package: authorizer.accesscontroller.v1alpha1

The service to serve Expand RPC requests.

Expand#

rpc Expand(ExpandRequest) ExpandResponse

Expands all the relation tuples for all of the subjects given in the SubjectSet.

Expand follows direct and indirect SubjectSets in a depth-first fashion.

NamespaceConfigService#

Package: authorizer.accesscontroller.v1alpha1

The service to administer namespace configurations.

WriteConfig#

rpc WriteConfig(WriteConfigRequest) WriteConfigResponse

WriteConfig upserts a namespace configuration.

If the namespace config already exists, the existing one is overwritten. If the new namespace config removes an existing relation, there must not be any relation tuples that reference it. Otherwise a FAILED_PRECONDITION status is returned.

To migrate away from a relation, please move all existing relation tuples referencing it over to the new relation and then delete the old relation once all tuples have been migrated.### ReadConfig

rpc ReadConfig(ReadConfigRequest) ReadConfigResponse

Read a namespace configuration.

ReadService#

Package: authorizer.accesscontroller.v1alpha1

A service to query Access Control Lists.

ListRelationTuples#

rpc ListRelationTuples(ListRelationTuplesRequest) ListRelationTuplesResponse

Lists relation tuples.

NOTE: This does not follow direct or indirect references through rewrites. If you need to follow indirect references through rewrites, please use the Expand API.

WriteService#

Package: authorizer.accesscontroller.v1alpha1

A service that defines APIs to manage relation tuple ACLs.

WriteRelationTuplesTxn#

rpc WriteRelationTuplesTxn(WriteRelationTuplesTxnRequest) WriteRelationTuplesTxnResponse

Mutates one or more relation tuples within a single transaction.

WatchService#

Package: authorizer.accesswatcher.v1alpha1

A service defining APIs to watch for changes to namespaces.

Watch#

rpc Watch(WatchRequest) WatchResponse

Watches for changes to relation tuples in one or more namespaces.

Messages#

RelationTuple#

RelationTuple relates an object with a subject.

While a tuple reflects a relationship between object and subject, they do not completely define the effective ACLs.

Field	Type	Description
namespace	string	The namespace this relation tuple lives in.
object	string	The object identifier related by this tuple. Objects live within the namespace of the tuple.
relation	string	The relation between the Object and the Subject.
subject	Subject	The subject related by this tuple.

Subject#

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

Field	Type	Description
oneof ref.id	string	A concrete subject id string for the subject.
oneof ref.set	SubjectSet	A SubjectSet that expands to more Subjects.

SubjectSet#

A SubjectSet refers to all subjects which have the same relation to an object.

Field	Type	Description
namespace	string	The namespace of the object and relation referenced in this SubjectSet.
object	string	The object selected by the subjects.
relation	string	The relation between the object and the subject(s).

CheckRequest#

The request for a CheckService.Check rpc.

Field	Type	Description
namespace	string	The namespace to evaluate the check within.
object	string	The object to check.
relation	string	The relation between the object and the subject.
subject	Subject	The subject to check.
snaptoken	string	Optional. The snapshot token that encodes the evaluation timestamp that this request will be evaluated no earlier than. If no snapshot token is provided the check request is evaluated against the most recently replicated version of the relation tuple storage. Leaving an empty snapshot token will reflect the latest changes, but it may incur a read penalty because the reads have to be directed toward the leaseholder of the replica that serves the data. We call requests without a snapshot token a content-change check, because such requests require a round-trip read but return the most recent writes and are thus good candidates for checking real-time content changes before an object is persisted.

CheckResponse#

The response for a CheckService.Check rpc.

Field	Type	Description
allowed	bool	A boolean indicating if the specified subject is related to the requested object. It is false by default if no ACL matches.
snaptoken	string	A snapshot token encoding the snapshot evaluation timestamp that the request was evaluated at.

ExpandRequest#

The request for an ExpandService.Expand rpc.

Field	Type	Description
subject_set	SubjectSet	The SubjectSet to expand.
snaptoken	string	Optional. The snapshot token that encodes the evaluation timestamp that this request will be evaluated no earlier than. If no snapshot token is provided the expand request is evaluated against the most recently replicated version of the relation tuple storage. Leaving an empty snapshot token will reflect the latest changes, but it may incur a read penalty because the reads have to be directed toward the leaseholder of the replica that serves the data.

ExpandResponse#

The response for an ExpandService.Expand rpc.

Field	Type	Description
tree	SubjectTree	The tree the requested SubjectSet expands to. The requested SubjectSet is the subject of the root. This field can be nil in some circumstances.

SubjectTree#

Field	Type	Description
node_type	NodeType	The type of the node.
subject	Subject	The subject this node represents.
children	repeated SubjectTree	The children of this node. This is unset if `node_type` is `NODE_TYPE_LEAF`.

ComputedSubjectset#

Computes the set of subjects that have the included relation within the same namespace.

This is useful to follow relations between an object and subject within the same namespace. If you want anyone with an 'editor' relation to also have 'viewer' this would be a good fit.

Field	Type	Description
relation	string	none

NamespaceConfig#

A namespace config defines the relations that exist between objects and subjects in in a namespace.

Field	Type	Description
name	string	The name of the namespace.
relations	repeated Relation	The relations that this namespace defines.

ReadConfigRequest#

The request for a NamespaceConfigService.ReadConfig rpc.

Field	Type	Description
namespace	string	The namespace whose config should be read.

ReadConfigResponse#

The response for a NamespaceConfigService.ReadConfig rpc.

Field	Type	Description
namespace	string	The namespace of the config.
config	NamespaceConfig	The namespace config for the given namespace.

Relation#

A Relation defines a type of relationship between an object and subject.

Relations can have rewrite rules that specify how the relation is computed relative to other relations defined within the same namespace or across other namespaces.

Field	Type	Description
name	string	The name of the relation (e.g. viewer, editor, or member).
rewrite	Rewrite	The rewrite rule for this relation, or nil if it references itself.

Rewrite#

Rewrites define sub-expressions that combine operations such as union or intersection. A rewrite sub-expression can be recursive and thus allows arbitrary logical expressions to be constructed.

Field	Type	Description
oneof rewrite_operation.union	SetOperation	Joins the children of the rewrite via set union.
oneof rewrite_operation.intersection	SetOperation	Joins the children of the rewrite via set intersection.

SetOperation#

Field	Type	Description
children	repeated SetOperation.Child	none

SetOperation.Child#

Field	Type	Description
oneof child_type.this	SetOperation.Child.This	none
oneof child_type.computed_subjectset	ComputedSubjectset	none
oneof child_type.tuple_to_subjectset	TupleToSubjectset	none
oneof child_type.rewrite	Rewrite	none

SetOperation.Child.This#

This references the defined relation directly.

Field	Type	Description

TupleToSubjectset#

Computes a tupleset from the input object, fetches relation tuples matching the tupleset, and computes the set of subjects from every fetched relation tuple.

This is useful to lookup relations in other namespaces or to create complex hierarchies between objects in multiple namespaces.

Field	Type	Description
tupleset	TupleToSubjectset.Tupleset	A tupleset defining the relation tuples that relate to the set of subjects that this TupleToSubjectset applies to.
computed_subjectset	ComputedSubjectset	The computed set of subjects that are looked up based on the expanded tupleset.

TupleToSubjectset.Tupleset#

Field	Type	Description
relation	string	none

WriteConfigRequest#

The request for a NamespaceConfigService.WriteConfig rpc.

Field	Type	Description
config	NamespaceConfig	The namespace config to upsert.

WriteConfigResponse#

The response for a NamespaceConfigService.WriteConfig rpc.

Field	Type	Description

ListRelationTuplesRequest#

Field	Type	Description
query	ListRelationTuplesRequest.Query	All field constraints are concatenated with a logical AND operator.
snaptoken	string	Optional. The snapshot token that encodes the evaluation timestamp that this request will be evaluated no earlier than.
page_size	int32	Optional. The maximum number of RelationTuples to return in the response.
page_token	string	Optional. A pagination token returned from a previous call to `ListRelationTuples` that indicates where the page should start at.

ListRelationTuplesRequest.Query#

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

Example use cases:

object only: display a list of all ACLs of one object
relation only: get all groups that have members; e.g. get all directories that have content
object & relation: display all subjects that have e.g. write 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, before writing it

Field	Type	Description
namespace	string	Required. The namespace to query.
object	string	Optional.
relations	repeated string	Optional.
subject	Subject	Optional.

ListRelationTuplesResponse#

Field	Type	Description
relation_tuples	repeated RelationTuple	The relation tuples matching the request query. The RelationTuple list is ordered from the newest RelationTuple to the oldest.
next_page_token	string	The token required to paginate to the next page.
is_last_page	bool	Indicates if this is the last page of paginated data. If `is_last_page` is true then using `next_page_token` in subsequent requests will return an error.

RelationTupleDelta#

Write-delta for a WriteRelationTuplesTxnRequest.

Field	Type	Description
action	RelationTupleDelta.Action	The action to do on the RelationTuple.
relation_tuple	RelationTuple	The target RelationTuple.

WriteRelationTuplesTxnRequest#

The request of a WriteService.WriteRelationTuplesTxn rpc.

Field	Type	Description
relation_tuple_deltas	repeated RelationTupleDelta	The write delta for the relation tuples operated in one single transaction. Either all actions commit or no changes take effect on error.

WriteRelationTuplesTxnResponse#

The response of a WriteService.WriteRelationTuplesTxn rpc.

Field	Type	Description
snaptokens	repeated string	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 WriteRelationTuplesTxnRequest request. If the RelationTupleDelta_Action was DELETE the snaptoken is empty at the same index.

WatchRequest#

The request for a WatchService.Watch rpc.

Field	Type	Description
namespaces	repeated string	The namespaces to start watching for changes to.
snaptoken	string	A snapshot token encoding a timestamp where changes should start watching from.

WatchResponse#

The response for a WatchService.Watch rpc.

Field	Type	Description
relation_tuple_delta	RelationTupleDelta	The relation tuple delta that occurred.
snaptoken	string	A snapshot token encoding the timestamp of the relation tuple change.

Enums#

NodeType#

An enumeration defining types of nodes within a SubjectTree.

Name	Number	Description
NODE_TYPE_UNSPECIFIED	0	none
NODE_TYPE_UNION	1	A node type which expands to a union of all children.
NODE_TYPE_INTERSECTION	3	A node type which expands to an intersection of the children.
NODE_TYPE_LEAF	4	A node type which is a leaf and contains no children. Its Subject is a subject id string unless the maximum call depth was reached.

RelationTupleDelta.Action#

An enumeration defining the actions or mutations that can be done on a RelationTuple.

Name	Number	Description
ACTION_UNSPECIFIED	0	An unspecified action. The `WriteRelationTuplesTxn` rpc ignores RelationTupleDeltas with an unspecified action.
ACTION_INSERT	1	Upserts a new RelationTuple. If the RelationTuple already exists no modification is done.
ACTION_DELETE	4	Deletes the RelationTuple. If the RelationTuple does not exist it's a no-op.

Scalar Value Types#

.proto Type	Notes	Go	C++	Java	Python	C#	PHP	Ruby
# double		float64	double	double	float	double	float	Float
# float		float32	float	float	float	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	int32	int	int	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	int64	long	int/long	long	integer/string	Bignum
# uint32	Uses variable-length encoding.	uint32	uint32	int	int/long	uint	integer	Bignum or Fixnum (as required)
# uint64	Uses variable-length encoding.	uint64	uint64	long	int/long	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	int32	int	int	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	int64	long	int/long	long	integer/string	Bignum
# fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	uint32	int	int	uint	integer	Bignum or Fixnum (as required)
# fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	uint64	long	int/long	ulong	integer/string	Bignum
# sfixed32	Always four bytes.	int32	int32	int	int	int	integer	Bignum or Fixnum (as required)
# sfixed64	Always eight bytes.	int64	int64	long	int/long	long	integer/string	Bignum
# bool		bool	bool	boolean	boolean	bool	boolean	TrueClass/FalseClass
# string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	string	String	str/unicode	string	string	String (UTF-8)
# bytes	May contain any arbitrary sequence of bytes.	[]byte	string	ByteString	str	ByteString	string	String (ASCII-8BIT)