Protocol Documentation

April 2, 2026 · View on GitHub

aserto/directory/common/v3/common.proto
aserto/directory/exporter/v3/exporter.proto
aserto/directory/importer/v3/importer.proto
aserto/directory/model/v3/model.proto
aserto/directory/openapi/v3/openapi.proto
aserto/directory/reader/v3/reader.proto
aserto/directory/writer/v3/writer.proto
Scalar Value Types

aserto/directory/common/v3/common.proto

Object

Field	Type	Description
type	string	object type identifier
id	string	object instance identifier
display_name	string	Deprecated. display name object (optional) (DEPRECATED)
properties	google.protobuf.Struct	property bag (optional)
created_at	google.protobuf.Timestamp	Deprecated. created at timestamp (UTC) (DEPRECATED)
updated_at	google.protobuf.Timestamp	last updated timestamp (UTC)
etag	string	object instance etag (optional)

ObjectIdentifier

Object identifier

Field	Type	Label	Description
object_type	string		object type identifier
object_id	string		object instance identifier

PaginationRequest

Pagination request

Field	Type	Label	Description
size	int32		requested page size, valid value between 1-100 rows (optional, default 100)
token	string		pagination start token (optional, default "")

PaginationResponse

Pagination response

Field	Type	Label	Description
next_token	string		next page token, when empty there are no more pages to fetch

Relation

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
relation	string	object relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
subject_relation	string	subject relation name (optional)
created_at	google.protobuf.Timestamp	Deprecated. created at timestamp (UTC) (DEPRECATED)
updated_at	google.protobuf.Timestamp	last updated timestamp (UTC)
etag	string	object instance etag (optional)

RelationIdentifier

Relation identifier

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
relation	string	object relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
subject_relation	string	subject relation name (optional)

Top

aserto/directory/exporter/v3/exporter.proto

ExportRequest

Field	Type	Label	Description
options	uint32		data export options mask
start_from	google.protobuf.Timestamp		start export from timestamp (UTC)

ExportResponse

Field	Type	Description
object	aserto.directory.common.v3.Object	object instance (data)
relation	aserto.directory.common.v3.Relation	relation instance (data)
stats	google.protobuf.Struct	object and/or relation stats (no data)

Option

Name	Number	Description
OPTION_UNKNOWN	0	nothing selected (default initialization value)
OPTION_DATA_OBJECTS	8	object instances
OPTION_DATA_RELATIONS	16	relation instances
OPTION_DATA	24	all data = OPTION_DATA_OBJECTS
OPTION_STATS	64	stats

Exporter

Method Name	Request Type	Response Type	Description
Export	ExportRequest	ExportResponse stream	export objects and relations as a stream

Top

aserto/directory/importer/v3/importer.proto

ImportCounter

Field	Type	Description
recv	uint64	number of messages received
set	uint64	number of messages with OPCODE_SET
delete	uint64	number of messages with OPCODE_DELETE
error	uint64	number of messages resulting in error
type	string	counter of type (object

ImportRequest

Field	Type	Description
op_code	Opcode	operation Opcode enum value
object	aserto.directory.common.v3.Object	object import message
relation	aserto.directory.common.v3.Relation	relation import message

ImportResponse

Field	Type	Description
object	ImportCounter	Deprecated. object import counter
relation	ImportCounter	Deprecated. relation import counter
status	ImportStatus	import status message
counter	ImportCounter	import counter per type

ImportStatus

Field	Type	Description
code	uint32	gRPC status code (google.golang.org/grpc/codes)
msg	string	gRPC status message (google.golang.org/grpc/status)
req	ImportRequest	req contains the original import request message

Opcode

Name	Number	Description
OPCODE_UNKNOWN	0
OPCODE_SET	1
OPCODE_DELETE	2
OPCODE_DELETE_WITH_RELATIONS	3

Importer

Method Name	Request Type	Response Type	Description
Import	ImportRequest stream	ImportResponse stream	import stream of objects and relations

Top

aserto/directory/model/v3/model.proto

Body

Field	Type	Label	Description
data	bytes		manifest content

DeleteManifestRequest

Field	Type	Label	Description
empty	google.protobuf.Empty		empty request

DeleteManifestResponse

Field	Type	Label	Description
result	google.protobuf.Empty		empty result

GetManifestRequest

Field	Type	Label	Description
empty	google.protobuf.Empty		empty request

GetManifestResponse

Field	Type	Description
metadata	Metadata	Manifest metadata
body	Body	Manifest content
model	google.protobuf.Struct	Model

Metadata

Field	Type	Label	Description
updated_at	google.protobuf.Timestamp		last updated timestamp (UTC)
etag	string		object instance etag (optional)

SetManifestRequest

Field	Type	Label	Description
body	Body		Manifest content

SetManifestResponse

Field	Type	Label	Description
result	google.protobuf.Empty		empty result

Model

Method Name	Request Type	Response Type	Description
GetManifest	GetManifestRequest	GetManifestResponse stream	get manifest instance
SetManifest	SetManifestRequest stream	SetManifestResponse	set manifest instance
DeleteManifest	DeleteManifestRequest	DeleteManifestResponse	delete manifest instance

Top

aserto/directory/openapi/v3/openapi.proto

Top

aserto/directory/reader/v3/reader.proto

CheckPermissionRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
permission	string	permission name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
trace	bool	collect trace information (optional)

CheckPermissionResponse

Field	Type	Label	Description
check	bool		check result
trace	string	repeated	trace information

CheckRelationRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
relation	string	relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
trace	bool	collect trace information (optional)

CheckRelationResponse

Field	Type	Label	Description
check	bool		check result
trace	string	repeated	trace information

CheckRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
relation	string	relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
trace	bool	collect trace information (optional)

CheckResponse

Field	Type	Label	Description
check	bool		check result
trace	string	repeated	trace information
context	google.protobuf.Struct		context

ChecksRequest

Field	Type	Label	Description
default	CheckRequest
checks	CheckRequest	repeated

ChecksResponse

Field	Type	Label	Description
checks	CheckResponse	repeated

GetGraphRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier (optional)
relation	string	relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier (optional)
subject_relation	string	subject relation name (optional)
explain	bool	return graph paths for each result (optional)
trace	bool	collect trace information (optional)

GetGraphResponse

Field	Type	Label	Description
results	aserto.directory.common.v3.ObjectIdentifier	repeated	matching object identifiers
explanation	google.protobuf.Struct		explanation of results
trace	string	repeated	trace information

GetObjectManyRequest

Field	Type	Label	Description
param	aserto.directory.common.v3.ObjectIdentifier	repeated	object identifier list

GetObjectManyResponse

Field	Type	Label	Description
results	aserto.directory.common.v3.Object	repeated	array of object instances

GetObjectRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
with_relations	bool	materialize the object relations objects (optional)

GetObjectResponse

Field	Type	Label	Description
result	aserto.directory.common.v3.Object		object instance
relations	aserto.directory.common.v3.Relation	repeated	object relations

GetObjectsRequest

Field	Type	Label	Description
object_type	string		object type identifier (optional)
page	aserto.directory.common.v3.PaginationRequest		pagination request (optional)

GetObjectsResponse

Field	Type	Label	Description
results	aserto.directory.common.v3.Object	repeated	array of object instances
page	aserto.directory.common.v3.PaginationResponse		pagination response

GetRelationRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
relation	string	relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
subject_relation	string	subject relation name (optional)
with_objects	bool	materialize relation objects (optional)

GetRelationResponse

Field	Type	Label	Description
result	aserto.directory.common.v3.Relation		relation instance
objects	GetRelationResponse.ObjectsEntry	repeated	map of materialized relation objects

GetRelationResponse.ObjectsEntry

Field	Type	Label	Description
key	string
value	aserto.directory.common.v3.Object

GetRelationsRequest

Field	Type	Description
object_type	string	object type identifier (optional)
object_id	string	object instance identifier (optional)
relation	string	relation name (optional)
subject_type	string	subject type identifier (optional)
subject_id	string	subject instance identifier (optional)
subject_relation	string	subject relation name (optional)
with_objects	bool	materialize relation objects (optional)
with_empty_subject_relation	bool	only return relations that do not have a subject relation (optional)
page	aserto.directory.common.v3.PaginationRequest	pagination request (optional)

GetRelationsResponse

Field	Type	Label	Description
results	aserto.directory.common.v3.Relation	repeated	array of relation instances
objects	GetRelationsResponse.ObjectsEntry	repeated	map of materialized relation objects
page	aserto.directory.common.v3.PaginationResponse		pagination response

GetRelationsResponse.ObjectsEntry

Field	Type	Label	Description
key	string
value	aserto.directory.common.v3.Object

Reader

Method Name	Request Type	Response Type	Description
GetObject	GetObjectRequest	GetObjectResponse	get object
GetObjectMany	GetObjectManyRequest	GetObjectManyResponse	get multiple objects
GetObjects	GetObjectsRequest	GetObjectsResponse	list objects
GetRelation	GetRelationRequest	GetRelationResponse	get relation
GetRelations	GetRelationsRequest	GetRelationsResponse	list relations
Check	CheckRequest	CheckResponse	check if subject has relation or permission with object
Checks	ChecksRequest	ChecksResponse	checks validates a set of check requests in a single roundtrip
CheckPermission	CheckPermissionRequest	CheckPermissionResponse	check permission (deprecated, use the check method) Deprecated: use directory.reader.v3.Check()
CheckRelation	CheckRelationRequest	CheckRelationResponse	check relation (deprecated, use the check method) Deprecated: use directory.reader.v3.Check()
GetGraph	GetGraphRequest	GetGraphResponse	get object relationship graph

Top

aserto/directory/writer/v3/writer.proto

DeleteObjectRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
with_relations	bool	delete object relations, both object and subject relations (optional)

DeleteObjectResponse

Field	Type	Label	Description
result	google.protobuf.Empty		empty result

DeleteRelationRequest

Field	Type	Description
object_type	string	object type identifier
object_id	string	object instance identifier
relation	string	object relation name
subject_type	string	subject type identifier
subject_id	string	subject instance identifier
subject_relation	string	subject relation name (optional)

DeleteRelationResponse

Field	Type	Label	Description
result	google.protobuf.Empty		empty result

SetObjectRequest

Field	Type	Label	Description
object	aserto.directory.common.v3.Object		object instance

SetObjectResponse

Field	Type	Label	Description
result	aserto.directory.common.v3.Object		object instance

SetRelationRequest

Field	Type	Label	Description
relation	aserto.directory.common.v3.Relation		relation instance

SetRelationResponse

Field	Type	Label	Description
result	aserto.directory.common.v3.Relation		relation instance

Writer

Method Name	Request Type	Response Type	Description
SetObject	SetObjectRequest	SetObjectResponse	set object instance
DeleteObject	DeleteObjectRequest	DeleteObjectResponse	delete object instance
SetRelation	SetRelationRequest	SetRelationResponse	set relation instance
DeleteRelation	DeleteRelationRequest	DeleteRelationResponse	delete relation instance

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)