What are role Checks?

Roles are unique identifiers representing granular access to the API. Every API method on has a unique Role name. Roles provide an easy way to grant access to your services based on access keys.

Roles can be assigned during the creation of an API Access Key, allowing granular role access checks per generated key. All System Events on have a one-to-one mapping to Roles.

Role checks are used to determine if an incoming HTTP request has authorization to access the requested resource. offers several integrated roles and custom roles that may be associated with a generated Access Key.

Available Roles

Name Description
cron::createcreate a new cron job
cron::destroydestroy cron jobs
cron::readread cron jobs
cron::resource::readread the database document for cron services
cron::updateupdate an existing cron job
datastore::deldestroy a cloud datastore document
datastore::getget a cloud datastore document
datastore::recentget recent cloud datastore documents
datastore::setset a new cloud datastore document
domain::createcreate a new domain or subdomain alias
domain::destroydestroy an existing domain or subdomain alias
domain::findsearch or list domain and subdomain aliases
domain::getget a domain or subdomain alias
domain::updateupdate an existing domain or subdomain alias
env::readread environment variables
env::writewrite environment variables
events::readread from the system event log
events::writewrite to the system event log
files::createReadStreamcreate a new cloud read file stream
files::createWriteStreamcreate a new cloud write file stream
files::downloaddownload a cloud file
files::readFileread a cloud file
files::readdirread a cloud directory
files::removeFileremove an existing cloud file
files::statperform a stat on a cloud file
files::uploadupload a new cloud file
files::writeFilewrite a new cloud file
hook::createcreate a new hook microservice
hook::destroydestroy a hook microservice
hook::findsearch or list hooks
hook::logs::readread the logs
hook::logs::writewrite to logs
hook::package::readread the package.json manifest for hook microservices
hook::presenter::readread the Presenter source code for hook microservices
hook::resource::readread the database document for hook microservices
hook::runrun any hook microservice
hook::source::readread the source code for hook microservices
hook::updateupdate the properties or sources of any hook microservice
hook::view::readread the View source code for hook microservices
keys::checkAccessdetermine if a key has valid role access for account
keys::createcreate a new api key
keys::destroydestroy api keys
keys::readread api keys

Custom Role Checks

Aside from the built-in roles provides, it's also possible to specify a custom role value when creating an API Access Key which can used later to check access using the keys.checkAccess HTTP API method ( available in SDK)

For Example, inside a Hook service as req.checkAccess(role, cb):

module['exports'] = function checkAccess (req, res) {
  req.checkAccess('custom::role', function(err, hasAccess){

This will be scoped to the hook_private_key HTTP parameter or to the current user session.