1 

Device Spaces Management

List device spaces

This call returns information on all device spaces, including name, the criteria used to create the device space, status, priority, device count, and the device space admins.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

GET

Request URI

api/v2/device_spaces

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Default: 0

Device space ID of the administrator.

 

limit

Parameter Type: Query

Data Type: Number

Min: 0 character

Max: 10,000 characters

Default: 10,000

Indicates the maximum number of entries to return. Must be at least 0 and no more than 10,000.

5000

offset

Parameter Type: Query

Data Type: Number

Min: 0

Max: 10,000,000

Default: 0

Indicates the index of the first entry to return.

 

excludeDeviceCount

Parameter Type: Query

Data Type: Boolean

Default: false

true = deviceCount field returned is always zero and you should ignore this value.

false = deviceCount field contains actual device count.

If you do not need the device count, then call it with "excludeDeviceCount=true," which yields faster results.

 

Response fields

Field

Description

results

An array of entry objects: id, device space name, criteria, status, priority, device count, and the admins of the device space.

totalCount

The total number of entries that the query matched.

resultCount

The number of entries that are being returned.

hasMore

Indicates that there are more entries available.

Sample request and response

Request

curl -X GET -H "Authorization: Basic bWlhZG1pbjpNaTRtYW4xMQ==" https://[mobileironcore]/api/v2/device_spaces?adminDeviceSpaceId=1&limit=50&sort&dir=ASC&offset=0&page=1&start=0

Response

{

    "results": [

        {

            "id": 1,

            "name": "Global",

            "criteria": "",

            "status": "ACTIVE",

            "priority": 1,

            "deviceCount": 319,

            "admins": "miadmin"

        }

    ],

    "totalCount": 1,

    "resultCount": 1,

    "hasMore": false

}

Get my device spaces

This call gets a list of device spaces to which the currently logged in user belongs.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

GET

Request URI

api/v2/device_spaces/mine

Request parameters

none

Response fields

Field

Description

results

An array of device spaces: id, device space name, and the description of the device space.

totalCount

The total number of entries that the query matched.

resultCount

The number of entries that are being returned.

hasMore

Indicates that there are more entries available.

Sample request and response

Request

curl -X GET -H "Authorization: Basic bWlhZG1pbjpNaTRtYW4xMQ==" https://[mobileironcore]/api/v2/device_spaces/mine?adminDeviceSpaceId=1&limit=50&sort&dir=ASC&offset=0&page=1&start=0

Response

{

    "results": [

        {

            "id": 1,

            "name": "Global",

            "description": null

        }

    ],

    "totalCount": 1,

    "resultCount": 1

}

List fields for device space criteria

This call returns a list of the advanced search fields used for creating a device space.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

GET

Request URI

api/v2/device_spaces/criteria

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Default: 0

Device space ID of the administrator.

 

Sample request and response

Request

curl -X GET -H "Authorization: Basic bWlhZG1pbjpNaTRtYW4xMQ==" https://[mobileironcore]/api/v2/device_spaces/criteria?adminDeviceSpaceId=1

Response

{{

    "results": [

        {

            "name": "common.home_country_code",

            "type": "STRING"

        },

        {

            "name": "common.home_country_name",

            "type": "STRING"

        },

        ... {

            "name": "user.user_id",

            "type": "STRING"

        }

    ],

    "totalCount": 35,

    "resultCount": 35

}

Create or update a device space

This call creates or updates a device space.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

POST

Request URI

api/v2/device_spaces

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Default: 0

Device space ID of the administrator.

 

name

Required

Parameter Type: Request body

Data Type: String

Name of the space. Name must be unique.

 

id

Required when updating a space

Parameter Type:

Data Type: Number

ID of the space. Used for updating a space.

 

parentId

Required

Parameter Type: Request body

Data Type: Number

ID of the parent device space. 1 is the ID for the Global device space

 

criteria

Required

Parameter Type: Request body

Data Type: String

Space criteria.

""criteria"":""\\""common.home_country_code\\"" =  \\""US\\""  AND \\""common.home_country_name\\"" =  \\""United States\\"""",""name"":""USA Devices""}"

Response fields

Field

Description

id

The ID of the created or updated device space.

Sample request and response

Request

curl "https://[mobileironcore]/api/v2/device_spaces?adminDeviceSpaceId=1" -H "authUserId: bWlhZG1pbg==" -H "Accept: application/json" -H "Content-type: application/json" --data-binary "{""parentId"":""1"",""criteria"":""\\""common.home_country_code\\"" =  \\""US\\""  AND \\""common.home_country_name\\"" =  \\""United States\\"""",""name"":""USA Devices""}"

Response

{

    "results": {

        "id": 4

    }

}

Delete a device space

This call marks a device space for deletion and then MobileIron Core deletes the marked device space within a few hours.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

DELETE

Request URI

api/v2/device_spaces/[id]

Request parameters

Parameter

Description

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Default: 0

Device space ID of the administrator.

id

Parameter Type: Path

Data Type: Number

ID of the device space to delete. If missing or 0 (zero), the call uses the value of the current device space.

Response fields

Field

Description

id

The ID of the device space marked for deletion.

Sample request and response

Request

curl "https://[mobileironcore]/api/v2/device_spaces/4?adminDeviceSpaceId=1" -X DELETE -H "Content-Type: application/json"

Response

{

    "results": {

        "id": 4

    }

}

Assign admins to device space

This call assigns admins to a device space.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

POST

Request URI

api/v2/device_spaces/[deviceSpaceId]/admins

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Min: 0

Default: 0

Device space ID of the administrator.

 

deviceSpaceId

Required

Parameter Type: Path

Data Type: Number

Min: 1

Max: 10,000,000

The ID of device space ID to which to assign admins

 

roles

Required

Parameter Type: Request body

Data Type: List

Min: 1

Max: 100

List of roles to assign to the admins. See Get a list of admin roles for the call you use to find the values for this parameter.

 

adminUsers

Parameter Type: Request body

Data Type: List

Min: 1

Max: 500

List of admin userIds (i.e., principals). Each element in the list must be no more than 50 characters in length. May not be used if adminLdapEntities is used.

 

adminLdapEntities

Parameter Type: Request body

Data Type: List

Min: 1

Max: 500

List of admin LDAP entities, composed of a name, an LDAP type and a DN. LDAP type choices are "GROUP", "USER", or "OU". May not be used if adminUsers parameter is used.

Note: LDAP entities are not validated against LDAP. You must to pass in the correct values.

 

Response fields

This call does not return any response fields, but does return the HTTP 200 OK response code upon success.

Sample request and response

Request

curl "https://[mobileironcore]/api/v2/device_spaces/3/admins?adminDeviceSpaceId=1" -H "Content-Type: application/json" --data-binary "{""roles"":[2,4,5,7,8,3,6,13,14,15,16,33,18,20,21,23,35],""adminLdapEntities"":[{""name"":""testuser000000"",""type"":""USER"",""dn"":""cn=testuser000000,ou=contacts,dc=auto2,dc=mobileiron,dc=com""}]}"

Request payload structure

{

    "roles": [

        2,

        4,

        5,

        7,

        8,

        3,

        6,

        13,

        14,

        15,

        16,

        33,

        18,

        20,

        21,

        23,

        35

    ],

    "adminLdapEntities": [

        {

            "name": "testuser000000",

            "type": "USER",

            "dn": "cn=testuser000000,ou=contacts,dc=auto2,dc=mobileiron,dc=com"

        }

    ]

}

Response

200 OK

Delete admins from device space

This call unassigns admins from a device space.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

DELETE

Request URI

api/v2/device_spaces/[deviceSpaceId]/admins

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Min: 0

Default: 0

Device space ID of the administrator.

 

deviceSpaceId

Required

Parameter Type: Path and Request body

Data Type: Number

Min: 1

Max: 10,000,000

The ID of device space from which to delete admins. This call requires this parameter in the request path and in the request body.

 

adminUsers

Parameter Type: Request body

Data Type: List

Min: 1

Max: 500

List of admin userIds (i.e., principals) to delete as admins. Each element in the list must be no more than 50 characters in length. May not be used if adminLdapEntities is used.

 

adminLdapEntities

Parameter Type: Request body

Data Type: List

Min: 1

Max: 500

List of admin LDAP entities to delete as admins, composed of a name, an LDAP type and a DN. LDAP type choices are "GROUP", "USER", or "OU". May not be used if adminUsers parameter is used.

Note: LDAP entities are not validated against LDAP. You must to pass in the correct values.

 

Response fields

This call does not return any response fields, but does return the HTTP 200 OK response code upon success.

Sample request and response

Request

curl "https://[mobileironcore]/api/v2/device_spaces/5/admins?adminDeviceSpaceId=1" -X DELETE -H "Content-Type: application/json" --data-binary "{""deviceSpaceId"":5,""adminLdapEntities"":[{""name"":""testuser000004"",""type"":""USER"",""dn"":""cn=testuser000004,ou=contacts,dc=auto2,dc=mobileiron,dc=com""}]}"

Response

200 OK

Get policy restrictions

This call lists the policy restrictions for the target device space.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

(You can also make this call with the Policy management > View policy role.)

HTTP method

GET

Request URI

/msa/v2/policy/restrictions?adminDeviceSpaceId=n&deviceSpaceId=n

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Min: 0

Default: 0

Device space ID of the administrator.

1

deviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Min: 1

Max: 10,000,000

The ID of device space whose settings to list

3

Response fields

Field

Description

results

Container describing the settings and the success of the call.

Sample request and response

Request

curl -X GET \

  'https://mobileiron_core/msa/v2/policy/restrictions?adminDeviceSpaceId=1&deviceSpaceId=3' \

  -H 'authorization: Basic 5555ZG1pbjpNaTRtYW4xMQ==' \

  -H 'cache-control: no-cache' \

  -H 'postman-token: 82baa5ef-b810-f602-1f2f-fd2d75dc91fb' \

  -d '{"policyRestrictions":[{"policyProfileType":"PRIVACY","creationAllowedInSpace":true,"overrideGlobalPolicies":false},{"policyProfileType":"SECURITY","creationAllowedInSpace":true,"overrideGlobalPolicies":false}]}'

Response

{

    "results": {

        "policyRestrictions": [

            {

                "policyProfileType": "PRIVACY",

                "creationAllowedInSpace": true,

                "overrideGlobalPolicies": false

            },

            {

                "policyProfileType": "SECURITY",

                "creationAllowedInSpace": true,

                "overrideGlobalPolicies": false

            }

        ],

        "deviceSpaceId": 3

    },

    "messages": [

        {

            "type": "Info",

            "messageKey": "com.mobileiron.vsp.messages.policy.restrictions.in.space.get.success",

            "localizedMessage": "Policy restrictions in space successfully fetched."

        }

    ]

}

Assign policy restrictions

This call sets which policy type admins in space can create. Along with this setting, space admins should also have proper roles to create/edit/delete policies in this space.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

POST

Request URI

msa/v2/policy/restrictions?deviceSpaceId

Request parameters

Parameter

Description

Sample Value

deviceSpaceId

Required

Parameter Type: Query

Data Type: Number

The ID of device space for which to configure policy restrictions.

3

policyRestrictions

Parameter Type: Request body

Data Type: JSON

Container for the policy restrictions parameters.

policyProfileType: The type of restriction to configure. Can be:
- PRIVACY
- SECURITY
creationAllowedInSpace: Specifies whether admins can create policies in the space. Can be:
- true
- false
overrideGlobalPolicies: Specify whether Privacy and Security policies created in the space override global policies. Can be:
- true: All policies created in this space will have higher priority than global policies. Relevant policies will be re-evaluated and if there are any changes, it will be re-pushed to the devices.
- false: All policies created in this space will have lower priority than global policies. Relevant policies will be re-evaluated and if there are any changes, it will be re-pushed to the devices.

(ignore the hyphens in the sample below. Do not use hyphens for the parameters)

 

{

    "policyRestrictions": [

        {

            "policyProfileType": "PRIVACY",

            "creationAllowedInSpace": true,

            "overrideGlobalPolicies": false

        },

        {

            "policyProfileType": "SECURITY",

            "creationAllowedInSpace": true,

            "overrideGlobalPolicies": false

        }

    ]

}

Response fields

Field

Description

messages

Container describing the success or failure of the call.

Sample request and response

Request

curl -X POST \

  'https://mobileiron_core/msa/v2/policy/restrictions?deviceSpaceId=3' \

  -H 'accept: application/json' \

  -H 'authorization: Basic 4555ZG1pbjpNaTRtYW4xMQ==' \

  -H 'content-type: application/json' \

  -d '{"policyRestrictions":[{"policyProfileType":"PRIVACY","creationAllowedInSpace":true,"overrideGlobalPolicies":false},{"policyProfileType":"SECURITY","creationAllowedInSpace":true,"overrideGlobalPolicies":false}]}'

Response

{

    "messages": [

        {

            "type": "Info",

            "messageKey": "com.mobileiron.vsp.messages.policy.restrictions.in.space.save.success",

            "localizedMessage": "Policy restrictions saved successfully for space: ForDocs.",

            "messageParameters": [

                "ForDocs"

            ]

        }

    ]

}

Change device space priority

This call changes the device space priority.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

POST

Request URI

api/v2/device_spaces/[deviceSpaceId]/change_priority

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Default: 0

Device space ID of the administrator.

 

deviceSpaceId

Required

Parameter Type: Path

Data Type: Number

The ID of device space whose priority to change.

 

deviceSpaceIdAboveMe

Parameter Type: Request body

Data Type: List

Min: 1

Max: 500

The ID of the device space whose priority is one step higher than the target device space.

Use 0 (zero) if the target device space is to have no other spaces above it.

 

Response fields

Field

Description

results

An array of information about the target device space, including id, name, parent device space ID, resultant priority, criteria used for creating the device space, status of the change, and the path.

Sample request and response

Request

curl "https://[mobileironcore]/api/v2/device_spaces/5/change_priority?adminDeviceSpaceId=1" -H "Content-type: application/json" --data "deviceSpaceIdAboveMe=4"

Response

{

    "results": {

        "id": 5,

        "name": "UK Devices",

        "parentId": 1,

        "priority": 2,

        "criteria": "\"common.home_country_code\" =  \"GB\"",

        "criteriaFields": "-",

        "status": "PENDING",

        "path": "/1/5/"

    }

}

Evaluate device spaces

This call evaluates the status of all device spaces. For example, if you mark a device space for deletion, you can then evaluate the device spaces to determine the status of the pending deletion.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Admin Management

Role Description: Manage administrators and device spaces

HTTP method

POST

Request URI

api/v2/device_spaces/evaluate

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Parameter Type: Query

Data Type: Number

Default: 0

Device space ID of the administrator.

 

Response fields

This call does not return any response fields, but does return the HTTP 200 OK response code upon success.

Sample request and response

Request

curl "https://[mobileironcore]/api/v2/device_spaces/evaluate?adminDeviceSpaceId=1" -H "Content-type: application/json" --data "includeLabelEvaluation=1"

Response

200 OK