Groups¶

On this page

Endpoints
Sample Entity
Entity Fields
Links
Examples

Endpoints¶

Get All Groups for a User¶

Get all groups for the current user.

GET /api/public/v1.0/groups

Create a Group¶

Specify only the name field.

copy

POST /api/public/v1.0/groups

The publicApiEnabled field is automatically set to true for groups created with the API. The response includes the agentApiKey for the group.

Get a Group¶

Get a single group by its ID.

copy

GET /api/public/v1.0/groups/GROUP-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.

copy

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

Get All Users in a Group¶

copy

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

Add Users to a Group¶

Add one or more existing users to a group.

copy

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 that the user should possess.

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

Remove a User from a Group¶

copy

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

Sample Entity¶

copy

{
  "id": "xxx",
  "name": "My Group",
  "hostCounts": {
    "arbiter": 2,
    "config": 1,
    "primary": 4,
    "secondary": 8,
    "mongos": 2.
    "master": 0,
    "slave": 0
  },
  "lastActiveAgent": ISODate("2014-02-05T07:23:34Z"),
  "activeAgentCount": 1,
  "replicaSetCount": 3,
  "shardCount": 2,
  "publicApiEnabled": true,
  "agentApiKey": "cbd728abd6a6d6c6b6d7826345dbcff0e",
  "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 all types, 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	Is the Public API enabled for this group? This is a read-only field that will always be true for groups created with the API. Note that for groups created in the Ops Manager UI, the only way to set this flag to `true` is by enabling the Public API for the group in the Settings tab.
`agentApiKey`	string	The API key for your agent. This field is only present in the response entity to a `POST` request. Thus, the API key will only be exposed at group creation time.

Links¶

Relation	Description
`self`	Me
`http://mms.mongodb.com/hosts`	All hosts in the group.
`http://mms.mongodb.com/users`	All users in the group.
`http://mms.mongodb.com/clusters`	All clusters in the group.
`http://mms.mongodb.com/alerts`	All open alerts for the group.
`http://mms.mongodb.com/alertConfigs`	All alert configurations for the group.
`http://mms.mongodb.com/backupConfigs`	All backup configurations for the group.
`http://mms.mongodb.com/agents`	All agents for the group.

Examples¶

Get a Group¶

copy

curl -u "username:apiKey" --digest -i "https://cloud.mongodb.com/api/public/v1.0/groups/5196d3628d022db4cbc26d9e"

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" : "2014-04-03T18:18:12Z",
  "activeAgentCount" : 1,
  "replicaSetCount" : 3,
  "shardCount" : 2,
  "links" : [ ... ]
}

Get All Groups for Current User¶

copy

curl -u "username:apiKey" --digest -i "https://cloud.mongodb.com/api/public/v1.0/groups"

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" : "2014-04-03T18:18:12Z",
    "activeAgentCount" : 1,
    "replicaSetCount" : 3,
    "shardCount" : 2,
    "links" : [ ... ]
  }, {
    // etc.
  } ],
  "links" : [ ... ]
}

Create a Group¶

copy

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

HTTP/1.1 201 Created
Location: https://cloud.mongodb.com/api/public/v1.0/groups/533daa30879bb2da07807696

{
  "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¶

copy

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -i -X POST "https://cloud.mongodb.com/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"
    }]
  }
]'

HTTP/1.1 200 OK

Delete a Group¶

copy

curl -u "username:apiKey" --digest -i -X DELETE "https://cloud.mongodb.com/api/public/v1.0/groups/533daa30879bb2da07807696"

HTTP/1.1 200 OK

Get Users in a Group¶

copy

curl -u "username:apiKey" --digest -i "https://cloud.mongodb.com/api/public/v1.0/groups/5356823bc0edc2788a835ed0/users"

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" : [ ... ]
}

Delete a User from a Group¶

copy

curl -u "username:apiKey" --digest -i -X DELETE "https://cloud.mongodb.com/api/public/v1.0/groups/5356823bc0edc2788a835ed0/users/5357e25a300490374243f425"

HTTP/1.1 200 OK

← Clusters Users →