Groups

One of the features offered by our API is the ability to group together users and resources for easier manipulation of access control.

All the endpoints and how to interface them are documented below

/groups

API Endpoint for handling all requests related to groups. Groups are used to group together users and resources for easier manipulation of access control. Users, doors, and computers all have separate groups, and when dealing with a group you must specify the type of group you are using. See specific method docs for more detail.

Resource Methods

/DELETE

Delete a group from this organization. Groups must not currently be used by policies to be deleted. It can be either a user or resource group, depending on the argument.

Parameters:

  • type – (Required) The type of the group to delete. Must be either “users” or “resources”

  • group_id – (Required) The id of the group to delete

Returns:

{success: "resources group successfully deleted!"}, 200

{"error": "error message"}, !200 on failure

/GET

Return a list of all the groups (and their contents) of a certain type (e.g., users or resources). Requires authentication.

Parameters:

  • type – (Required) The type of group to get. The two supported types are [‘users’, ‘resources’]

  • resource_type – (Optional) If the type parameter is specified as resource, further specification of the resource type is optinally available with this parameter. The two supported types are [‘COMPUTER’, DOOR’]

Returns:

`type=COMPUTER`_
[{  'id': 123,
    'name': "Joe's Computers",
    'count': 1,
    'items': [{
        'resource_id': 298,
        'resource_group_id': 123,
        'org_id': 1,
        'name': 'Joe's Desktop',
        'uuid': 'eb90ef53-5521-449c-95bb-3e1378eaf3az',
        'public_key': '-----BEGIN CERTIFICATE-----',
        'resource_type': 'COMPUTER',
        'resource_subtype': None,
        'status': 'ACTIVE',
        'resource_status_id': None,
        'updated': None,
        'seen': None,
        'unique_id': 298 # Unique identifier of this laptop
        },
        <more resources>
        ],
    'unique_id': 123   # Unique identifier of this resource group
    },
    <more groups>
], 200
`type=USERS`_
[{  'id': 217,
    'name': 'Interns',
    'count': 1,
    'items': [
        {'email_id': 762,
        'user_group_id': 217,
        'user_id': 769,
        'email': 'joe@developer.com',
        'unique_id': 762  # The unique user id,
        },
        <more users>
        ],
    'unique_id': 217  # Unique identifier of this user group
    },
    <more groups>
    ], 200

{"error": "error message"}, !200 on failure

/POST

Modify the members of a group in this organization by adding or deleting users or resources from the group.

Parameters:

  • type – (Required) String users or resources

  • group_id – (Required) Int representing the group id of the group being modified

  • add_ids – (Optional) list of ids that will be added to the group

  • del_ids – (Optional) list of ids that will be deleted from the group

Returns:

{success: "Group has been successfully updated!"}, 200

{"error": "error message"}, !200 on failure

/PUT

Create a new group and add it to the current organization. The group can be either a user or resource group.

Parameters:

  • type – (Required) The type of group to create. Either “users” or “resources”

  • name – (Required) The name of the group to create

  • add_ids – (Required) A list of IDs to add to the group. For users ids are from the email_id returned in a get request to the users endpoint. For resources ids are from the resource_id returned in a get request to the resources endpoint. Formatted as [1, 2,…]

  • resource_type – (Optional) The type of resource to create. Only used if type is “resources”. Either “COMPUTER” or “DOOR”

Returns:

{success: "Group has been successfully created!", group_id: 2}, 200

{"error": "error message"}, !200 on failure

/missinggroupitems

This API is used to get the users or resources that are not in a given group. See method documentation for use details.

type: users or resources

Resource Methods

/GET

This endpoint handles all the requests to the missinggroupitems API. It is used to get the users or resources that are not in a given group.

Parameters:

  • type – (Required) The type of the group to get the missing items for. Must be either “users” or “resources”

  • id – (Required) The id of the group to get the missing items for

Returns:

[{"email_id": 2, "first_name": "", "last_name": "", "email": "sheep@allthenticate.com", "unique_name": "  (sheep@allthenticate.com)", "name": " "}], 200

{"error": "error message"}, !200 on failure