Was this helpful?

You control your app users' access to application resources by defining roles and permission rules. In your API BaaS application, you assign application users a role that represents a set of permissions. Through these permissions, you allow users to perform certain operations (GET, POST, PUT, or DELETE) on specific resources. When the user submits a request via your app code to the API BaaS API, the user’s permissions are checked against the resource paths that the user is trying to access. The request succeeds only if access to the resource is allowed by the permission rules you specify.

You specify roles for unauthenticated users and those who authenticate as an Application User, as defined in Authenticating users and application clients. Roles are not applied for the other authentication levels: Application, Admin User, and Organization. Access at these levels can't be restricted by roles and permission rules. You should allow clients to authenticate at these levels sparingly and carefully.

Roles included by default

When defining user access to your application's data, you create roles, specify permission rules for them, then associate users with the roles. Your API BaaS applications include three predefined roles when you create an application.

The following table lists the three roles included by default. Note that two of these are in effect and applied from the time your application is created (until you change them). The API BaaS applies the following default behavior:

  1. An unauthenticated user is automatically added to the Guest role so that they can register for a user account.
  2. A user who has a user account and authenticates with it is automatically added to the Default role. Note that by default, this role is very permissive. Be sure to restrict it with specific permission rules before deploying to production.
Role Description Notes
Guest Default for unauthenticated users. Includes a basic set of permissions for unregistered or unauthenticated users. Users are automatically added to the Guest role before they’re authenticated. After they’re authenticated, users are automatically added to the Default role. Grants permission for a user to create a user account and for their device to be registered. You can change permission rules based on your goals for unregistered user access. This role is designed to provide access for people who haven't yet registered, and allow them to register.
Default Default for authenticated users. Includes permissions for the set of operations you want an authenticated user to be able to perform. Users are added to this role after they're authenticated.
By default, grants full access for all resources in your application. A first task in securing your application should be to restrict access by redefining this role to narrow the access it provides. Remove the default full permission rule and add restrictive permission rules for a production deployment.

Unused until you associate it with users or groups. By default, includes no permissions that provide access.

Grants no access. Consider this a blank slate. Add permission rules and associate this role with users and groups as needed.

Note: The Administrator role is not the same as an organization administrator -- that is, someone who authenticates as an Admin User. The Admin User is an implicit user created when you create an organization. After authenticating, the Admin User has full access to all of the administration features of the API BaaS API. By comparison, the Administrator role is simply a role (initially without permissions) that can be assigned to any user.

Defining custom roles and permissions in the admin portal

Use the Admin Portal to make role and permission rule changes. On the left sidebar of the portal, click Users, then click Roles. This displays the roles defined for the application. To create a role, click the Add button (it looks like a person's silhouette). To delete a role, select the role you want to delete and click the Remove button (it looks like a trash can). To view the privileges in a role, click the role.

When preparing an application for production use, a good first step is to edit permission rules for the Default role. This role will be applied for every user who authenticates as an Application User.

The admin portal is the best place to manage roles. While you can manage roles and permissions programmatically (see Role), security-related calls from a mobile app will pose a security risk. Consider doing so only from a server-side web application.

For easy-to-read examples, this section expresses permission rules in this way:

<operations>:<entity path pattern>
  • <operations> is a comma-delimited set of REST operations (GET, PUT, POST, DELETE) that are allowed for the specified entity path.
  • <entity path pattern> is a parameter evaluated using Apache Ant pattern matching (see http://ant.apache.org/manual/dirtasks.html#patterns).

For example, in the Default role, first remove the permission rule that grants full access to all authenticated users. You could then begin by creating a rule that grants access for the authenticated user to makes changes only to data associated with their account.



Suppose you created a role named "worker". Here’s what the privileges for the role might look like:


Notice that specific privileges for operations are represented using HTTP verbs like GET, POST, and so on in the Permissions. The path indicates the resource path for which the permissions apply. The permissions apply to all resources in the specified path directory and its subdirectories. As currently specified, the worker role has GET permission on the base directory path (/) and all resource paths below it (in other words, all resource paths).

To add a permission:

  1. Click Add Permission.
  2. In the New Permission dialog, in the Path box, enter the entity path pattern.
  3. Select check boxes for the operations you want to allow, as appropriate. For example, the following adds permission to create, read, and update widgets:

  4. Click Add to add and the permission to the role.


Defining custom roles and permissions programmatically

Use the POST method to create a new application role.

Example request

curl -X POST "https://api.usergrid.com/my-org/my-app/roles/ -d '{"name":"manager","title":"Manager","permission" : "get,put,post,delete:/users/me/groups"}'

It is recommended that you use the Admin Portal for administrative activities instead of using JavaScript to do them programmatically in your app.

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_role name: 'manager', title: 'Manager', 'permission' : 'get,put,post,delete:/users/me/groups'

The example assumes use of the Node.js module.

var options = {
    	permission : 'get,put,post,delete:/users/me/groups'
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call        

Permission rule examples

Here are some examples to illustrate how permissions are specified:

  • Authenticated user can change any data related to the:
  • A permission the permits the current user to make any changes to resources associated with them:
  • A permission that allows someone to look at a specific user:
  • A permission that allows the current user to see his activity feed:

    The ${user} in the entity path refers to a variable that represents the current user’s UUID.

  • A permission allowing linked entities to be read:

    The /** in the entity path is a wildcard that matches everything under that path. This means that the full specification matches multiple resource paths, including, but not limited to, the following:

  • A permission that allows the current user to add himself or another user to a group:


thanks, very useful

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.