Navigation
You were redirected from a different version of the documentation. Click here to go back.

Groups

Endpoints

Get All Groups for the Current User

GET /api/public/v1.0/groups

To query by group tags, use the tag query parameter, as shown below. If you specify multiple tag values, the group must have all the specified values. You must have the Global Read Only or Global Owner role to view tags.

GET /api/public/v1.0/groups?tag=ABC&tag=DEF

Get a Group by ID

GET /api/public/v1.0/groups/GROUP-ID

Get a Group by Name

GET /api/public/v1.0/groups/byName/GROUP-NAME

Get a Group by Agent API Key

Each group has an agent API key. To retrieve the key from the Ops Manager interface, click Settings, then Group Settings.

GET /api/public/v1.0/groups/byAgentApiKey/AGENT-API-KEY

Get All Users in a Group

GET /api/public/v1.0/groups/GROUP-ID/users

Create a Group

Specify only the name field.

POST /api/public/v1.0/groups

The response includes the agentApiKey for the group.

If you include the tags field when creating a group, Ops Manager will check whether you have the Global Owner role, which gives permission to create tags. If you do not, the entire POST request will be rejected.

Add Users to a Group

Add one or more existing users to a group.

POST /api/public/v1.0/groups/GROUP-ID/users

You must send an array of entities, even if you’re only adding a single user. For each user that you wish to add, specify the user ID and the roles the user should possess. For possible role values, see the description of the roles.roleName field in the users resource’s field descriptions.

If you specify a user that is already a member of the group, their existing roles are overwritten with the specified permissions.

Change a Group’s Name

Use PATCH to replace the group’s name field. You must have the group owner role.

PATCH /api/public/v1.0/groups/GROUP-ID/

Add or Remove Tags from a Group

Add or remove tags by using PATCH to replace the entire tags array with a new set of tags. The command overwrites all existing tags. You must have the global owner role to add or remove tags.

PATCH /api/public/v1.0/groups/GROUP-ID/

Map LDAP Groups to Ops Manager Roles

If Ops Manager uses LDAP to authenticate users, use this endpoint to map LDAP groups to Ops Manager roles.

PATCH /api/public/v1.0/groups/GROUP-ID/

Replace the entire ldapGroupMappings array with a new set of mappings. The ldapGroupMappings array must specify a mapping for the Ops Manager GROUP_OWNER role. All other group roles are optional. The array can not map Ops Manager global roles.

The PATCH command overwrites all existing mappings.

You must have the group owner role to map LDAP groups to Ops Manager roles.

Remove a User from a Group

DELETE /api/public/v1.0/groups/GROUP-ID/users/USER-ID

Delete a Group

Once a group is deleted, its name cannot be reclaimed. Thus, if you create a group named My Group and then delete it, you will not be able to create another group named My Group.

DELETE /api/public/v1.0/groups/GROUP-ID

Sample Entity

The following is a sample response document:

{
  "id": "xxx",
  "name": "My Group",
  "hostCounts": {
    "arbiter": 2,
    "config": 1,
    "primary": 4,
    "secondary": 8,
    "mongos": 2.
    "master": 0,
    "slave": 0
  },
  "lastActiveAgent": ISODate("2016-08-05T07:23:34Z"),
  "activeAgentCount": 1,
  "replicaSetCount": 3,
  "shardCount": 2,
  "publicApiEnabled": true,
  "agentApiKey": "cbd728abd6a6d6c6b6d7826345dbcff0e",
  "tags": [ "DEV", "PRODUCT" ],
  "ldapGroupMappings" : [ {
    "roleName": "GROUP_OWNER",
    "ldapGroups": [ "group-owner" ]
    }, ... ],
  "links": [ ... ]
}

Entity Fields

Name Type Description
id string The unique identifier for the group.
name string The display name for the group.
hostCounts object The total number of hosts by type. The embedded fields should be self-explanatory.
lastActiveAgent date The time Ops Manager last updated the activeAgentCount total for the group. Ops Manager runs a job every 30 minutes to record the number of active agents of any type (Monitoring, Backup, Automation).
activeAgentCount number

The number of active agents of any type (Monitoring, Backup, Automation) sending regular pings to Ops Manager.

The value is refreshed every 30 minutes. If you start a new agent or stop an existing one, the change can take up to 30 minutes to show up in the activeAgentCount field.

replicaSetCount number The total number of replica sets for this group.
shardCount number The total number of shards for this group.
publicApiEnabled boolean Indicates that the Public API is enabled for this group. This is a read-only field that will always be true.
agentApiKey string

The agent API key for the group.

You must have the Owner or Global Read Only role to view this field.

tags string array

The tags assigned to the group for use in programmatically identifying the group. To view tags you must have either the Global Read Only or Global Owner role. To create or edit tags, you must be a Global Owner.

A group can have up to 10 tags. Tags follow these rules:

  • Are case-sensitive
  • Can contain these characters:
    • A through Z
    • 0 through 9
    • . (period)
    • _ (underscore)
    • - (dash)
  • Are limited to 32 characters
ldapGroupMappings object array For LDAP-backed Ops Manager, the mappings of LDAP groups to Ops Manager roles. Only present for LDAP-backed Ops Manager.
ldapGroupMappings.roleName string The Ops Manager user role. For role values, see the description of the roles.roleName field in the users resource.
ldapGroupMappings.ldapGroups string array The LDAP group(s) that map to the Ops Manager role.

Examples

Get All Groups for the Current User

Request

curl -u "username:apiKey" --digest -i "https://<ops-manager-host>/api/public/v1.0/groups"

Response

HTTP/1.1 200 OK

{
  "totalCount" : 6,
  "results" : [ {
    "id" : "5196d3628d022db4cbc26d9e",
    "name" : "API Example",
    "hostCounts" : {
      "arbiter" : 0,
      "config" : 1,
      "primary" : 3,
      "secondary" : 4,
      "mongos" : 2,
      "master" : 0,
      "slave" : 0
    },
    "lastActiveAgent" : "2016-02-03T18:18:12Z",
    "activeAgentCount" : 1,
    "replicaSetCount" : 3,
    "shardCount" : 2,
    "publicApiEnabled" : true,
    "agentApiKey" : "cbd728abd6a6d6c6b6d7826345dbcff0e",
    "links" : [ ... ]
  }, {
    // etc.
  } ],
  "links" : [ ... ]
}

Get a Group by ID

Request

curl -u "username:apiKey" --digest -i "https://<ops-manager-host>/api/public/v1.0/groups/5196d3628d022db4cbc26d9e"

Response

HTTP/1.1 200 OK

{
  "id" : "5196d3628d022db4cbc26d9e",
  "name" : "API Example",
  "hostCounts" : {
    "arbiter" : 0,
    "config" : 1,
    "primary" : 3,
    "secondary" : 4,
    "mongos" : 2,
    "master" : 0,
    "slave" : 0
  },
  "lastActiveAgent" : "2016-02-03T18:18:12Z",
  "activeAgentCount" : 1,
  "replicaSetCount" : 3,
  "shardCount" : 2,
  "publicApiEnabled" : true,
  "agentApiKey" : "cbd728abd6a6d6c6b6d7826345dbcff0e",
  "links" : [ ... ]
}

Get a Group by Agent API Key

Request

curl -u "username:apiKey" --digest -i "https://<ops-manager-host>/api/public/v1.0/groups/byAgentApiKey/cbd728abd6a6d6c6b6d7826345dbcff0e"

Response

HTTP/1.1 200 OK

{
  "id" : "5196d3628d022db4cbc26d9e",
  "name" : "API Example",
  "hostCounts" : {
    "arbiter" : 0,
    "config" : 1,
    "primary" : 3,
    "secondary" : 4,
    "mongos" : 2,
    "master" : 0,
    "slave" : 0
  },
  "lastActiveAgent" : "2016-02-03T18:18:12Z",
  "activeAgentCount" : 1,
  "replicaSetCount" : 3,
  "shardCount" : 2,
  "publicApiEnabled" : true,
  "agentApiKey" : "cbd728abd6a6d6c6b6d7826345dbcff0e",
  "links" : [ ... ]
}

Get All Users in a Group

Request

curl -u "username:apiKey" --digest -i "https://<ops-manager-host>/api/public/v1.0/groups/5356823bc0edc2788a835ed0/users"

Response

HTTP/1.1 200 OK

{
  "totalCount" : 2,
  "results" : [ {
    "id" : "5357e25a300490374243f425",
    "username" : "user1@example.com",
    "emailAddress" : "user1@example.com",
    "firstName" : "User",
    "lastName" : "One",
    "roles" : [ {
      "groupId" : "5356823bc0edc2788a835ed0",
      "roleName" : "GROUP_USER_ADMIN"
    } ],
    "links" : [ ... ]
  }, {
    "id" : "5356823b3004dee37132bb7b",
    "username" : "user2@example.com",
    "emailAddress" : "user2@example.com",
    "firstName" : "User",
    "lastName" : "Deux",
    "roles" : [ {
      "groupId" : "5356823bc0edc2788a835ed0",
      "roleName" : "GROUP_OWNER"
    }, {
      "groupId" : "5356823bc0edc2788a835ecd",
      "roleName" : "GROUP_OWNER"
    } ],
    "links" : [ ... ]
  } ],
  "links" : [ ... ]
}

Create a Group

Request

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -i -X POST "https://<ops-manager-host>/api/public/v1.0/groups" --data '
{
  "name": "API Example 2"
}'

Response

HTTP/1.1 201 Created

{
  "id" : "533daa30879bb2da07807696",
  "name" : "API Example 2",
  "activeAgentCount" : 0,
  "replicaSetCount" : 0,
  "shardCount" : 0,
  "publicApiEnabled": true,
  "agentApiKey": "cbd747d7b7b711de45aa3ff0e",
  "hostCounts" : {
    "arbiter" : 0,
    "config" : 0,
    "primary" : 0,
    "secondary" : 0,
    "mongos" : 0,
    "master" : 0,
    "slave" : 0
  },
  "links" : [ ... ]
}

Add Users to a Group

Request

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -i -X POST "https://<ops-manager-host>/api/public/v1.0/groups/533daa30879bb2da07807696/users" --data '
[
  {
    "id": "5329c8dfe4b0b07a83d67e7d",
    "roles": [{
      "roleName": "GROUP_READ_ONLY"
    }]
  },
  {
    "id": "5329c906e4b0b07a83d691ba",
    "roles": [{
      "roleName": "GROUP_MONITORING_ADMIN"
    }, {
      "roleName": "GROUP_BACKUP_ADMIN"
    }]
  }
]'

Response

HTTP/1.1 200 OK

Add or Remove Tags from a Group

The following command adds and removes tags by replacing the group’s tags array with the new set of desired tags. The command overwrites the existing array.

Request

curl -u "username:apiKey" --digest -i -H "Content-Type: application/json" -X PATCH "https://<ops-manager-host>/api/public/v1.0/groups/533daa30879bb2da07807696" --data '
{
  "tags": [ "DEV", "PROD", "WEB" ]
}'

Response

HTTP/1.1 200 OK

{
  "id" : "5196d3628d022db4cbc26d9e",
  "name" : "API Example",
  "hostCounts" : {
    "arbiter" : 0,
    "config" : 1,
    "primary" : 3,
    "secondary" : 4,
    "mongos" : 2,
    "master" : 0,
    "slave" : 0
  },
  "lastActiveAgent" : "2016-08-04T14:12:11Z",
  "activeAgentCount" : 1,
  "replicaSetCount" : 3,
  "shardCount" : 2,
  "publicApiEnabled" : true,
  "agentApiKey" : "cbd728abd6a6d6c6b6d7826345dbcff0e",
  "tags": [ "DEV", "PROD", "WEB" ],
  "links" : [ ... ]
}

Remove a User from a Group

Request

curl -u "username:apiKey" --digest -i -X DELETE "https://<ops-manager-host>/api/public/v1.0/groups/5356823bc0edc2788a835ed0/users/5357e25a300490374243f425"

Response

HTTP/1.1 200 OK

Delete a Group

Request

curl -u "username:apiKey" --digest -i -X DELETE "https://<ops-manager-host>/api/public/v1.0/groups/533daa30879bb2da07807696"

Response

HTTP/1.1 200 OK
←   Groups and Users Users  →