Sandbox Permissions

By default, sandboxes can be accessed only by their owner and the subuser who created them. If other subusers need to access the same sandbox the owner may grant them permission using the following APIs.

Note

Requests may be safely sent multiple times and without checking if the permission is already granted. Permissions can be revoked by sending a DELETE request with the same URL used in the grant.

List Permissions Granted on all accessible Sandboxes

List Permissions Granted on a Sandbox

Grant Everyone Permissions

Provides access to a sandbox for all subusers.

Grant Specific Subusers Permissions

Provides access to a sandbox for a single subuser.

Revoke a Permission Granted to Everyone

Revokes a permission granted to all subusers. This does not revoke permissions granted to specific subusers.

Revoke a Permission Granted to Specific Subusers

Revokes a permission granted to a single subuser. If a non-owner user can access a sandbox, the user can revoke its own permission.

Example

  1. Create an empty sandbox.

    POST https://routecloud.telogis.com/v1/sandboxes?name=acl_demo_sandbox.

    Body:

     {

 }

    Response:

     {
 	"sandbox_id": "Jz_7zZn_r0-DIYN3xpMeZA",
 	"created_time": "2018-06-05T01:21:15.741"
 }

  2. List Permissions.

    GET https://routecloud.telogis.com/v1/sandboxes/Jz_7zZn_r0-DIYN3xpMeZA/acl.

    Response:

     {
 	"access_controls": [
 		// An access key is automatically generated for each new sandbox
 		{
 			"permission": "edit",
 			"access_key": "y4vB46BioeqTMoRu"
 		}
 	]
 }

  3. Grant permission.

    POST https://routecloud.telogis.com/v1/sandboxes/Jz_7zZn_r0-DIYN3xpMeZA/acl?permission=edit_and_delete&subuser=joe&subuser=adam.

  4. List Permissions.

    GET https://routecloud.telogis.com/v1/sandboxes/Jz_7zZn_r0-DIYN3xpMeZA/acl.

    Response:

     {
 	"access_controls": [
 		{
 			"permission": "edit",
 			"access_key": "y4vB46BioeqTMoRu"
 		},
 		// The newly granted permission
 		{
 			"permission": "edit_and_delete",
 			"subuser": "joe"
 		},
 		{
 			"permission": "edit_and_delete",
 			"subuser": "adam"
 		}
 	]
 }

Query Parameters

  • subuser={subuser} - The name of the user who is having the permission granted or revoked. If a person logs in as "company:user", "user" is the value that should be provided here. You can add multiple user names. If no subuser is specified, grants are applied to all subusers.
  • permission={permission} - Required. The sandbox_permission to grant or revoke.

Status Codes

  • 204 - Success.
  • 400 - The request contained an invalid sandbox_id or permission.
  • 401 - Authentication required.
  • 403 - The authenticated user does not have permission to perform this action.
  • 404 - The requested sandbox was not found.

sandbox_permission

  • "edit_and_delete" - Allows a user to view, add revisions to, and delete a sandbox.

all_sandbox_acl_response

Name Type Description
all_access_controls sandbox_acl_response[] List of currently granted permission for the user.

sandbox_acl_response

Name Type Description
sandbox_id string The ID of the sandbox.
sandbox_name string The name of the sandbox.
access_controls sandbox_access_control[] List of currently granted permission for the sandbox.

The sandbox_id and sandbox_name are returned only when permissions of all accessible Sandboxes are requested.

sandbox_access_control

Name Type Description
access_key string Any user provided with this access key will be granted the permission.
permission sandbox_permission The permission this grant provides.
subuser string The name of the subuser this permission is granted to. This will be "null" if the permission is not for a specific user.

The sandbox_access_control always specifies a permission and may specify a subuser or access_key. If neither subuser nor access_key is specified the permission has been granted to all subusers.