Chapter 9. Teams Administration API

The Team Administration API allows Users with the required Permissions to manage teams at different levels of the Platform.

9.1. Requirements

To be able to administer teams the user must authenticate to the specific domain, either by logging in and using the returned cookie, or by using an API key located in the API Key Management section of the User Profile in Studio.

In addition, the logged in user must be a Member of a Team(s) with the following permissions:

  • Reseller

    • Administrator (View & Edit)

OR

  • Customer

    • Administrator (View & Edit)

OR

  • Domain

    • Administrator (View & Edit)

9.2. List Teams

9.2.1. Description

Lists the Teams available to the User based on the Permissions assigned to the Teams that the User is a Member of.

9.2.2. JSON Team Definition

The following JSON Object is the JSON definition of a Team referred to in the response bodies in the Teams Administration Platform API. 

{
    //Team Identifier
    "_id": "teamid1234",
    //The Business Objects that the Team has access to at different levels of the
    //Platform.
    "business-objects": {
        "cluster": [
            "<Cluster Name>"
          ],
          "cluster/reseller": [
            "<Reseller Id>"
          ],
          "cluster/reseller/customer": [
            "<Customer Id>"
          ]
    },
    //Array Of Users IDs Assigned to the Team.
    "users": ["userid1234"],
    //Permissiions assigned to the Team at Different Levels of the Platform
    "perms": {
        "cluster/reseller": "read"
        "cluster/reseller/customer": "write"
        "cluster/reseller/customer/domain": "read"
    },
    //Is this Team a Default Team or a User Created Team.
    "defaultTeam": true/false,
    //A User-defined description of a Team.
    "desc": "This is a Team.",
    //The Name of a Team.
    "name": "Team 1",
    //Timestamp of the last time the team was updated.
    "updated": "<1413466521479>",
    //A User-Defined code for the team.
    "code": "Team Code"
}

9.2.3. Endpoint

  • URI: /api/v2/admin/teams
  • Method: GET

9.2.4. Request Body

{}

9.2.5. Response Body

9.2.5.1. Success

// Array of JSON Objects Representing A Team
[
    "<JSON Team Definition>",
    "<JSON Team Definition>"
]

9.2.5.2. Error

{
    "error": {
        "error": "<Error Message>"
    }
}

9.3. List Teams For User

9.3.1. Description

This endpoint lists the Teams that a User with ID userId is a Member of.

9.3.2. Endpoint

  • URI: /api/v2/admin/users/<userId>/teams
  • Method: GET

9.3.3. Request Body

{}

9.3.4. Response Body

9.3.4.1. Success

[
    "<JSON Team Definition>"
]

9.3.4.2. Error

{
    "error": {
        "error": "<Error Message>"
    }
}

9.4. View Team Details

9.4.1. Description

View the full JSON definition for a Team with ID teamId.

9.4.2. Endpoint

  • URI: /api/v2/admin/teams/<teamId>
  • Method: GET

9.4.3. Request Body

{}

9.4.4. Response Body

9.4.4.1. Success

{
    "<JSON Team Definition>"
}

9.4.4.2. Error

{
    "error": {
        "error": "<Error Message>"
    }
}

9.5. Create Team

9.5.1. Description

Create a new User-Defined Team.

9.5.2. Endpoint

  • URI: /api/v2/admin/teams
  • Method: POST

9.5.3. Request Body

{
    //A User-Defined name for the Team.
    "name":"User Team",
    //A User-Definied code for the Team.
    "code":"user-team",
    //A User-Definied description of the team.
    "desc":"A Team Created By A User",
    //Permissions Assigned to the Team at differnent levels of the Platform
    "perms":{
        "cluster": [
            "<Cluster Name>"
        ],
        "cluster/reseller": [
            "<Reseller Id>"
        ],
        "cluster/reseller/customer": [
            "<Customer Id>"
        ]
    },
    //User IDs of Users assigned to the Team.
    "users":[],
    //IDs of Business Objects assigned to the Team at different levels of the Platform.
    "business-objects":{
        "cluster/reseller": "read"
    }
}

9.5.4. Response Body

9.5.4.1. Success

{
    "<JSON Team Definition>"
}

9.5.4.2. Error

{
    "error": {
        "error": "<Error Message>"
    }
}

9.6. Remove Team

9.6.1. Description

Remove a Team with ID teamId.

9.6.2. Endpoint

  • URI: /api/v2/admin/teams/<teamId>
  • Method: DELETE

9.6.3. Request Body

{}

9.6.4. Response Body

9.6.4.1. Success

{
    "JSON Team Definition"
}

9.6.4.2. Error

{
    "error": "<Error Message>"
}

9.7. Add User To A Team

9.7.1. Description

Adding a user with ID userId to a Team with ID teamId

9.7.2. Endpoint

  • URI: /api/v2/admin/teams/<teamId>/user/<userId>
  • Method: POST

9.7.3. Request Body

{
    "guid": "<userId>"
}

9.7.4. Response Body

9.7.4.1. Success

{
    "<JSON Team Definition>"
}

9.7.4.2. Error

{
    "error": "<Error Message>"
}

9.8. Remove User From A Team

9.8.1. Description

Removes a User with ID userId from a Team with ID teamId.

9.8.2. Endpoint

  • URI: /api/v2/admin/teams/<teamId>/user/<userId>
  • Method: DELETE

9.8.3. Request Body

{}

9.8.4. Response Body

9.8.4.1. Success

{
    "<JSON Team Definition>"
}

9.8.4.2. Error

{
    "error": "<Error Message>"
}