Assign Roles

Until a Service Account has at least one Role applied, it may authenticate with the Enterprise API, but it has no authorization to view any resources.

caution

The Roles API is an idempotent upsert. Be cautious not to inadvertently overwrite and lose existing roles.

Tech Notes

• Each Service Account can only be assigned one Role for each type
• Each Role may have one or many resources assigned
• Changes to roles take effect immediately

HTTP Request Body Examples

Account Admin

[
    {
        "roleName": "ACCOUNT_ADMIN",
        "resources": {
            "locationGroups": [],
            "locations": [],
            "applyToAccount": true
        }
    }
]

Location Groups

A Role applied to a Location Group will give implicit access to all Locations that are children of the specified Location Group.

[
    {
        "roleName": "IOT_MANAGER",
        "resources": {
            "locationGroups": [
                "92bc8660-99dc-4285-b1e0-ce9b6dd95d65",
                "0b4ee02c-83a2-4613-ac68-57a1e2d8ca08"
            ],
            "locations": [],
            "applyToAccount": false
        }
    }
]

Locations

For more complex scenarios, it is possible to layer multiple different role types across different types of resources, in different parts of the resource tree.

In this case, the Service Account is assigned a Location Group-level IoT Manager role, with an additional less-permissive role into a single Location in a different Location Group.

[
    {
        "roleName": "IOT_MANAGER",
        "resources": {
            "locationGroups": [
                "0b4ee02c-83a2-4613-ac68-57a1e2d8ca08"
            ],
            "locations": [],
            "applyToAccount": false
        }
    },
    {
        "roleName": "IOT_MEMBER",
        "resources": {
            "locationGroups": [],
            "locations": [
                "f3694fa8-f4c7-4758-958b-8a61372acf40"
            ],
            "applyToAccount": false
        }
    }
]

Layering Multiple Roles

[
    {
        "roleName": "IOT_MEMBER",
        "resources": {
            "locationGroups": [],
            "locations": [
                "6e5f5247-38e3-4f3b-b70e-3d5b63789a6f",
                "53376cb5-ce61-49d5-93be-0d50c1c7276a",
                "f3694fa8-f4c7-4758-958b-8a61372acf40"
            ],
            "applyToAccount": false
        }
    }
]

Rate Limiting

Service Account Roles are highly flexible, and may have a large scope of access. Rate limits will apply to the uniqueness of the Service Account itself, so please consider these variables when designing programmatic access to the Enterprise API endpoints. Visit Rate Limits for a comprehensive list of limits.