Target Access API (v7.2.0+)

This article describes the API endpoints used to view and manage the access that Users and Groups are granted to Targets. Access can be granted directly to a User or indirectly via Group membership. The following endpoints are covered:

  • /api/target/access: Returns the Groups and Users that have access to a Target, including Users with access both directly and via Group membership.
  • /api/group_target: View, grant, and revoke a Group's access to Targets.
  • /api/user_target: View, grant, and revoke a User's access to Targets.

Prerequisites:

NOTES:

  • Access requirements differ per endpoint:
    • /api/target/access: Requires permission to the Target.
    • /api/group_target: Requires an Admin, or a Power User with permission to edit the Group.
    • /api/user_target: Requires an Admin; Target access can be granted only to Power Users.

Table of Contents

  1. Access Admin > System > API Toolkit
  2. Retrieve Users and Groups with Access to Target
  3. Configure Group_Target Associations
    1. Retrieve Groups With Access to Target
    2. Grant Group Access to Target
    3. Remove Group Access from Target
  4. Configure User_Target Associations
    1. Retrieve Users With Access to Target
    2. Grant User Access to Target
    3. Remove User Access from Target

1. Access Admin > System > API Toolkit

2. Retrieve Users and Groups with Access to Target

A GET request to /api/target/access/id/<id> returns the Groups and Users that have access to the specified Target. The response shows the Groups with access, the Users with direct access, and all Users with access (directly or via Group), excluding Admins and members of an "All Access" Group.

  1. Item: target/access
  2. Method: GET
  3. ID: Enter the ID of the Target.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "target_access": {
    "direct_groups": [
      {
        "id": 53,
        "name": "Analytics Team"
      }
    ],
    "direct_users": [
      {
        "id": 168,
        "display_name": "Test User"
      }
    ],
    "all_users": [
      {
        "id": 193,
        "display_name": "John Powers",
        "sources": [
          {
            "source": "group",
            "id": 53,
            "name": "Analytics Team"
          }
        ]
      }
    ]
  }
}

Fields Description

Parameter NameValue TypeDescription
target_access
objectContains the Groups and Users with access to the Target.
direct_groups
arrayGroups with access to the Target.
Below are the Group object fields of the direct_groups array:
id
integerThe ID of the Group.
name
stringThe name of the Group.
direct_users
arrayUsers with direct access to the Target.
all_users
arrayAll Users with access to the Target (directly or via Group), excluding Admins and members of an "All Access" Group.
Below are the User object fields of the direct_users and  all_users arrays:
id
integerUser ID.
display_name
stringUser's first and last name.
sources
arraySource(s) of the User's access. (all_users only)
Below are the source object fields from the sources array:
source
stringSource of access. ("direct" or "group")
id
integerThe ID of the Group through which the User has access. For directly assigned Users, the value is 0.
name
stringThe name of the Group through which the User has access. For directly assigned Users, the value is an empty string.

3. Configure Group_Target Associations

The /api/group_target endpoint retrieves which Groups have access to which Targets, and allows granting and removing that access. Each data entry has a unique ID and represents a single Group-to-Target mapping.

3.1. Retrieve Groups With Access to Target

  • A GET request to /api/group_target returns all Group-to-Target access mappings.
  • A GET request to /api/group_target/id/<id> returns a single Group-to-Target mapping by ID.
  1. Item: group_target
  2. Method: GET
  3. Filter the results with the following parameters:
    • group: The ID of the Group.
    • target: The ID of the Target.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "group_targets": [
    {
      "id": 1,
      "group": 2,
      "target": 53
    },
    {
      "id": 12,
      "group": 4,
      "target": 204
    }
  ]
}

Fields Description

Field NameValue TypeDescription
id
integerThe ID of the group_target data entry.
group
integerThe ID of the Group.
target
integerThe ID of the Target.

3.2. Grant Group Access to Target

NOTE: A Group cannot be granted access to a Target it already has access to.

A POST request to /api/group_target grants a Group access to the Target.

  1. Item: group_target
  2. Method: POST
  3. Enter the ID of an existing group_target data entry.
  4. Choose JSON request and provide the following values:
    • group: The ID of the Group to grant access to.
    • target: The ID of the Target.
  5. Enter an API Token.
  6. [Run request]

3.3. Remove Group Access from Target

A DELETE request to /api/group_target/id/<id> removes a Group's access to the Target.

  1. Item: group_target
  2. Method: DELETE
  3. Enter the ID of the group_target data entry to be deleted.
  4. Enter an API Token.
  5. [Run request]

4. Configure User_Target Associations

The /api/user_target endpoint retrieves which Users have access to which Targets, and allows granting and removing that access. Each data entry has a unique ID and represents a single User-to-Target mapping.

4.1. Retrieve Users With Access to Target

  • A GET request to /api/user_target returns all User-to-Target access mappings.
  • A GET request to /api/user_target/id/<id> returns a single User-to-Target mapping by ID.
  1. Item: user_target
  2. Method: GET
  3. Filter the results with the following parameters:
    • user: The ID of the User.
    • target: The ID of the Target.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "user_targets": [
    {
      "id": 1,
      "user": 2,
      "target": 53
    },
    {
      "id": 8,
      "user": 14,
      "target": 78
    }
  ]
}

Fields Description

Field NameValue TypeDescription
id
integerThe ID of the user_target data entry.
user
integerThe ID of the User.
target
integerThe ID of the Target.

4.2. Grant User Access to Target

NOTES:

  • A User cannot be granted access to a Target they already have access to.
  • Target access can be granted only to Power Users.
  • This endpoint requires an Admin.

A POST request to /api/user_target grants a User access to the Target.

  1. Item: user_target
  2. Method: POST
  3. Enter the ID of an existing user_target data entry.
  4. Choose JSON request and provide the following values:
    • user: The ID of the Power User to grant access to.
    • target: The ID of the Target.
  5. Enter an API Token.
  6. [Run request]

4.3. Remove User Access from Target

A DELETE request to /api/user_target/id/<id> removes a User's access to the Target.

  1. Item: user_target
  2. Method: DELETE
  3. Enter the ID of the user_target data entry to be deleted.
  4. Enter an API Token.
  5. [Run request]