Working with Subaccounts

This article describes how to make use of Digi Remote Manager APIs to work with subaccounts.

Introduction

This article describes how to make use of Digi Remote Manager APIs to work with subaccounts.

When an account has multiple subaccounts:

• Devices can be assigned to the parent group or a subaccount and be moved between the accounts by a user of the parent account
• Users can be assigned to a child subaccount and those users only have access to devices in the child group

v1/subaccounts API

The v1/subaccounts API is used to create, edit, and delete subaccounts.

Use GET /ws/v1/subaccounts/inventory to get a list of the parent account and all subaccounts.

POST to /ws/v1/subaccounts/inventory to create an account. An example payload is:

{
   "company_name": "Company ABC",
   "email": "user@company-abc.com",
   "username": "user-company-abc",
   "password": "xxxx",
   "name": "My display name",
   "notes": "Any notes that might be relevant for the parent account. The sub account cannot see the name, notes or tags fields. For example: The security procedures are under review for this account.",
   "tags": [ "Good Standing", "Gold Plan" ]
}

The body of the response will contain a customer_id field which is the key used for making other API requests for the subccount.

{
  "company_name": "Company ABC",
  "username": "user-company-abc",
  "password": "xxx",
  "email": "user@company-abc.com",
  "customer_id": 74214,
  "name": "My display name",
  "notes": "Any notes that might be relevant for the parent account. The sub account cannot see the name, notes or tags fields. For example: The security procedures are under review for this account.",
  "tags": [
    "Good Standing",
    "Gold Plan"
  ]
}

The following APIs would be used to get, update, and delete that subaccount:

• GET /ws/v1/subaccounts/inventory/74214

• PUT /ws/v1/subaccounts/inventory/74214 with a payload that has the requested changes

• DELETE /ws/v1/subaccounts/inventory/74214

For information on the API, see v1/subaccounts.

Viewing Inventory Across All Subaccounts

After creating subaccounts and assigning devices to them, the account-filter header is used to get results that include the items in the parent account and all subaccounts.

Use this API to get a list of all devices in the parent and all subaccounts

curl -u 'parentuser' -H "account-filter: all" https://remotemanager.digi.com/ws/v1/devices/inventory

The account-filter header can be used to get lists of items which include the parent and all subaccounts from APIs such as:

• GET v1/devices/inventory
• GET v1/jobs/inventory
• GET v1/users/inventory
• GET v1/configs/inventory

Working with an item in a subaccount

Once an item is found, use the actor header to work with it. For example, to update a device in a subaccount use a PUT with an API request in the format:

curl -u 'parentuser' -H "actor: 74214" -X PUT -d '{"notes": "user data here"}' https://remotemanager.digi.com/ws/v1/devices/inventory/00000000-00000000-00000000-00000000

Similarly, use the actor header with any API call to allow items to be created, updated, or deleted in the subaccount.

Use a POST to create a device in the subaccount with the format:

curl -u 'parentuser' -H "actor: 74214"  -H 'Content-Type: application/json' -X POST -d '{"id": "00000000-00000000-00000000-00000000", "install_code" : "INSTALLCODE"}' https://remotemanager.digi.com/ws/v1/devices/inventory

When the actor header is used on a GET, only items in the subaccount will be returned.

Examples of using the Headers

The table below shows what the result will be when a parent account user makes an API call to GET /ws/v1/devices/inventory using the specified headers. The account is set up with a parent account and 2 subaccounts.

ParentAccount (customer_id = 50)

ChildAccount-A (customer_id=55) and ChildAccount-B (customer_id=56)