• Home
  • Guides
  • Reference
  • Support

    Show / Hide Table of Contents
    • API Overview
      • Overview
      • Authentication
      • Retrieving API Results
      • Referenced vs Inline Entities
      • Choosing API Response Data
      • Handling API Errors
    • separator
    • Vehicle Routing Endpoints
      • Path
    • Optimization Endpoints
      • Instantiate
      • Build
      • Assignment Restrictions
      • Optimize
      • Sequence
      • Evaluate
      • Recommend
      • Insert
      • Centroids
      • Zones
      • Consolidate By Job Restrictions
      • Consolidate By Route Assignments
    • Geocoding Endpoints
      • Geocode
      • Reverse Geocode
    • Task Endpoints
      • List
      • Status
      • Result
      • Cancel
    • Sandbox Endpoints
      • List
      • Create
      • Rename
      • Retrieve
      • Update
      • Delete
      • Revisions
      • Add Revision
      • Expiry
      • Permissions
    • Verizon Connect Fleet Integration Endpoints
      • Pull Platform Data
      • Sync Platform Data
      • List Platform Territories
    • Other Endpoints
      • Canonicalize
      • Route Cards
      • Validate
      • Version
    • separator
    • Request Types
      • problem
      • capacity_metric
      • depot
      • driver
      • driver_break
      • job
      • job_template
      • job_type
      • load_amount
      • marker
      • problem_defaults
      • route
      • schedule
      • settings
      • shift
      • shift_override
      • shift_pattern
      • shift_pattern_assignment
      • stop
      • vehicle
      • zone
      • variance
    • Response Types
      • instantiate_response
      • problem_response
      • problem_aggregates
      • driver_response
      • geocoded_location
      • recommend_option
      • route_response
      • schedule_response
      • schedule_instantiate_response
      • stop_response
      • violation
    • Meta Types
      • task_redirect_response
      • task_status_response
      • validate_response
    • Sandbox Types
      • delta
      • array_delta
      • dict_delta
      • keyed_array_delta
      • object_delta
      • set_delta
      • revision
      • revision_created_response
      • revision_response
      • sandbox_response
    • Common Types
      • date_range
      • day_of_week
      • hazmat_load_type
      • id
      • latlon
      • stop_type
      • time_window
      • custom
      • polygon
    • Primitive Types
      • boolean
      • date
      • datetime
      • float
      • integer
      • string
      • timespan

    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

    • GET https://routecloud.telogis.com/v1/sandboxes/all/acl.
    • Authentication required.
    • Response body: all_sandbox_acl_response.

    List Permissions Granted on a Sandbox

    • GET https://routecloud.telogis.com/v1/sandboxes/{sandbox_id}/acl.
    • Authentication required.
    • Response body: sandbox_acl_response.

    Grant Everyone Permissions

    • POST https://routecloud.telogis.com/v1/sandboxes/{sandbox_id}/acl?permission={permission}.
    • Authentication required.

    Provides access to a sandbox for all subusers.

    Grant Specific Subusers Permissions

    • POST https://routecloud.telogis.com/v1/sandboxes/{sandbox_id}/acl?subuser={subuser}&permission={permission}.
    • Authentication required.

    Provides access to a sandbox for a single subuser.

    Revoke a Permission Granted to Everyone

    • DELETE https://routecloud.telogis.com/v1/sandboxes/{sandbox_id}/acl?permission={permission}.
    • Authentication required.

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

    Revoke a Permission Granted to Specific Subusers

    • DELETE https://routecloud.telogis.com/v1/sandboxes/{sandbox_id}/acl?subuser={subuser}&permission={permission}.
    • Authentication required.

    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.