Permissions allow you to define user access to perform GET, POST, PUT, or DELETE operations on specific resources. When the user submits a request via your app code to the Usergrid 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.
In Usergrid, permissions are represented in the following format:
<operations>:<resource_path>
<operations>: A comma-delimited set of HTTP methods (GET, PUT, POST, DELETE) that are allowed for the specified resource path. For example, get, post would allow only GET and POST requests to be made to the specified resource.<resource_path>: The path to the resources to be accessed. For example, /users would apply the permission to the users collection, while /users/Tom would apply the permission to only the user entity with username ‘Tom’.Complex paths can be defined using Apache Ant pattern syntax. The following special path variables are supported for the construction of complex paths:
Permissions can only be assigned to user, group or role entities. Assigning permissions to roles can be particularly useful, as it allows you to create sets of permissions that represent complex access definitions, which can then be assigned to user and group entities. For more on roles, see Using Roles.
curl -X POST https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions -d '{"permission":<permissions>}'
Parameters
Parameter Description
org Organization UUID or organization name app Application UUID or application name collection The collection of the entity that the permissions are to be assigned to. entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted. permissions The permissions to assign to the entity. See Permissions syntax for format.
For collections, Valid values are users and groups.
For example, the following cURL request would give the user ‘Tom’ POST permission to the /users collection:
curl -X POST https://api.usergrid.com/your-org/your-app/users/Tom/permissions -d '{"permission":"post:/users"}'
The newly assigned permission is returned in the data property of the response:
{
"action" : "post",
"application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
"params" : { },
"uri" : "https://api.usergrid.com/your-org/your-app",
"entities" : [ ],
"data" : [ "post:/users" ],
"timestamp" : 1402349612382,
"duration" : 19,
"organization" : "your-org",
"applicationName" : "your-app"
}
Using a DELETE request, you can remove one of more permissions from a user, group, or role entity.
curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions?=<permissions>
Parameters
Parameter Description
org Organization UUID or organization name app Application UUID or application name collection The collection of the entity that the permissions are to be assigned to. Valid values are users and groups. entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted. permissions The permissions to assign to the entity. See Permissions syntax for format.
curl -X DELETE https://api.usergrid.com/your-org/your-app/users/Tom/permissions?permission=post:/users
The deleted permission is returned in the params.permission property of the response:
{
"action" : "delete",
"application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
"params" : {
"permission" : [ "post:/users" ]
},
"uri" : "https://api.usergrid.com/your-org/your-app",
"entities" : [ ],
"data" : [ "post:/assets" ],
"timestamp" : 1402349951530,
"duration" : 20,
"organization" : "your-org",
"applicationName" : "your-app"
}