Concepts: Check API

A Check call is a call to the Authzed API to validate whether a particular user has a particular permission (via a relation) on a particular object.

Forming a Check#

A Check call is formed by specifying two pieces of information:

  • The test relation: A block containing the namespace, relation and object to check
  • The user: A user against which to check the permission

Example#

Let's say we wanted to check if a user someusername had read permission on object somedocument.

We'd form our test relation and user as follows:

Test Relation#

thetenant/document:somedocument#read

namespaceobjectrelation
thetenant/documentsomedocumentread

Translation: Check read relation for somedocument under the thetenant/document namespace

User#

thetenant/user:someusername#...

namespaceobjectrelation
thetenant/usersomeusername...

Translation: Check for user thetenant/user someusername

tip

... is a special relation that is predefined and means "use this whole object as the user"

Making the Check call#

To make a check call, issue a CheckRequest to the API:

CheckRequest {
test_userset: ObjectAndRelation {
namespace: 'thetenant/document'
object_id: 'somedocument'
relation: 'read'
}
user: {
userset: ObjectAndRelation {
namespace: 'thetenant/user'
object_id: 'someusername'
relation: '...'
}
}
}

The Check call will return whether someusername has read on somedocument:

CheckResponse {
result: NOT_MEMBER
}

at_revision#

The optional (but recommended) at_revision paramter on Check calls is for a Zookie, which allows for bounded staleness.

info

When should I specify at_revision?

Ideally? Always. Specifying the at_revision allows Authzed to validate that the permissions requested are not stale for the current version of the object.

To learn more about why this is important, read about the New Enemy Problem.