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

Users

Overview

The users resource allows you to create and update users and retrieve user information. This resource also provides an endpoint for creating the first user in a system and retrieving a Public API key for use in future API calls. The endpoint for creating the first user is the only endpoint you can use without first having an API key.

Endpoints

Get a User by ID

To retrieve the USER-ID for a user, see Get All Users in a Group.

GET /api/public/v1.0/users/USER-ID

You can always retrieve your own user account. Otherwise, you must be a global user or you must have the user admin role in at least one group that is common between you and the user you are retrieving.

Get a User by Name

GET /api/public/v1.0/users/byName/USER-NAME

You can always retrieve your own user account. Otherwise, you must be a global user or you must have the user admin role in at least one group that is common between you and the user you are retrieving.

Create a User

Create a new user. All fields are required.

POST /api/public/v1.0/users

Create the First User

POST /api/public/v1.0/unauth/users

This endpoint is available only when the Ops Manager instance has no users. This is the only API call you can make without first having an API key.

The user created through this endpoint is automatically granted the GLOBAL_OWNER role. The returned document includes the new user’s Public API key, which you can use to make further API calls.

The endpoint does not create a group, but you can use the new user and API key to create a group through the Groups resource in the API. You cannot login to Ops Manager until after you have created a group.

Update a User

Update an existing user using the fields provided. Unspecified fields will preserve their current values. You cannot specify the password for security reasons.

PATCH /api/public/v1.0/users/USER-ID

Sample Entity

{
  "id": "xxx",
  "username": "somebody",
  "password": "abc123",
  "emailAddress": "somebody@qa.example.com",
  "mobileNumber": "2125551234",
  "firstName": "John",
  "lastName": "Doe",
  "roles": [
      {
        "groupId": "8491812938cbda83918c",
        "roleName": "GROUP_OWNER"
      },
      {
        "groupId": "4829cbda839cbdac3819",
        "roleName": "GROUP_READ_ONLY"
      }
  ],
  "links": [ ... ]
}

Entity Fields

Name Type Description
id string Unique identifier.
username string Ops Manager username.
password string Password. This field is NOT included in the entity returned from the server. It can only be sent in the entity body when creating a new user.
emailAddress string Email address.
mobileNumber string Mobile number.
firstName string First name.
lastName string Last name.
roles object array Role assignments.
roles.groupId string The group ID in which the user has the specified role. Note that for the “global” roles (those whose name starts with GLOBAL_) there is no groupId since these roles are not tied to a group.
roles.roleName string

The name of the role. Possible values are:

  • GROUP_AUTOMATION_ADMIN
  • GROUP_BACKUP_ADMIN
  • GROUP_MONITORING_ADMIN
  • GROUP_OWNER
  • GROUP_READ_ONLY
  • GROUP_USER_ADMIN
  • GLOBAL_AUTOMATION_ADMIN
  • GLOBAL_BACKUP_ADMIN
  • GLOBAL_MONITORING_ADMIN
  • GLOBAL_OWNER
  • GLOBAL_READ_ONLY
  • GLOBAL_USER_ADMIN

Examples

Get a User by ID

Request

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

Response

HTTP/1.1 200 OK

{
  "id" : "533dc19ce4b00835ff81e2eb",
  "username" : "jane",
  "emailAddress" : "jane@qa.example.com",
  "firstName" : "Jane",
  "lastName" : "D'oh",
  "roles" : [ {
    "groupId" : "533daa30879bb2da07807696",
    "roleName" : "GROUP_USER_ADMIN"
  } ],
  "links": [ ... ]
}

Get a User by Name

Request

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

Response

HTTP/1.1 200 OK

{
  "emailAddress" : "jane@qa.example.com",
  "firstName" : "Jane",
  "id" : "533dc19ce4b00835ff81e2eb",
  "lastName" : "D'oh",
  "roles" : [ {
    "groupId" : "533daa30879bb2da07807696",
    "roleName" : "GROUP_USER_ADMIN"
  } ],
  "links": [ ... ]
}

Get All Users in a Group

Request

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

Response

HTTP/1.1 200 OK

{
  "totalCount": 3,
  "results": [ {
    "id" : "5329c8dfe4b0b07a83d67e7d",
    "username" : "jdoe",
    "emailAddress" : "jdoe@example.com",
    "firstName" : "John",
    "lastName" : "Doe",
    "roles" : [ {
      "groupId" : "5329cb6e879bb2da07806511",
      "roleName" : "GROUP_OWNER"
    }, {
      "groupId" : "5196d3628d022db4cbc26d9e",
      "roleName" : "GROUP_READ_ONLY"
    }, {
      "groupId" : "533daa30879bb2da07807696",
      "roleName" : "GROUP_READ_ONLY"
    } ],
    "links": [ ... ]
  }, {
    // etc.
  } ],
  "links": [ ... ]
}

Create the First User

Request

curl -H "Content-Type: application/json" -i -X POST "http://<ops-manager-host>/api/public/v1.0/unauth/users" --data '
{
  "username": "jane.doe@mongodb.com",
  "emailAddress": "jane.doe@mongodb.com",
  "password": "Passw0rd.",
  "firstName": "Jane",
  "lastName": "Doe"
}'

Response

HTTP/1.1 201 Created

{
  "user": {
    "username": "jane.doe@mongodb.com",
    "roles": [
      {
        "roleName": "GLOBAL_OWNER"
      }
    ],
    "lastName": "Doe",
    "id": "533dc19ce4b00835ff81e2eb",
    "firstName": "Jane",
    "emailAddress": "jane.doe@mongodb.com",
    "links": [ ... ]
  },
  "apiKey": "1234abcd-ab12-cd34-ef56-1234abcd1234"
}

Create a User

Request

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -i -X POST "https://<ops-manager-host>/api/public/v1.0/users" --data '
{
  "username": "jane",
  "emailAddress": "jane.doe@mongodb.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "password": "M0ng0D8!:)",
  "roles": [{
    "groupId": "533daa30879bb2da07807696",
    "roleName": "GROUP_USER_ADMIN"
  }]
}'

Response

HTTP/1.1 201 Created

{
  "id" : "533dc19ce4b00835ff81e2eb",
  "username" : "jane",
  "emailAddress" : "jane.doe@mongodb.com",
  "firstName" : "Jane",
  "lastName" : "Doe",
  "roles" : [ {
    "groupId" : "533daa30879bb2da07807696",
    "roleName" : "GROUP_USER_ADMIN"
  } ],
  "links" : [ ... ]
}

Update a User

Request

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -i -X PATCH "https://<ops-manager-host>/api/public/v1.0/users/533dc19ce4b00835ff81e2eb" --data '
{
  "emailAddress": "jane@qa.example.com",
  "lastName": "D'oh"
}'

Response

HTTP/1.1 200 OK

{
  "id" : "533dc19ce4b00835ff81e2eb",
  "username" : "jane",
  "emailAddress" : "jane@qa.example.com",
  "firstName" : "Jane",
  "lastName" : "D'oh",
  "roles" : [ {
    "groupId" : "533daa30879bb2da07807696",
    "roleName" : "GROUP_USER_ADMIN"
  } ],
  "links" : [ ... ]
}
←   Groups Whitelist  →