Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

REST users

A user represents a person with certain access permissions. Users can be local to the application or derived from a central authentication server such as LDAP. Different users can have different profile information, team assignments, group assignments, and permission settings in this product.

GET /v1/users

Returns all users.

Filters

  • keyword — String value of a user's first_name, last name, login, or ID
  • email — String value of a user's email address
  • last_name — String value of a user's last name
  • first_name — String value of a user's first name
  • active — Boolean value to show active users (default is to show only active users)
  • inactive — Boolean value to show inactive users
  • root — Boolean value to show root users

Common attributes

  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not Found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/users?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/users?token=[api_token]

An example of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "keyword":"admin" } }' http://[rails_host]/v1/users?token=[api_token]

GET /v1/users/[id]

Returns a user by ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to show is not found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/users/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/users/[id]?token=[api_token]

POST /v1/users

Creates a new user from posted data.

Required attributes

  • login — String for the user login
  • email — String email address for the user
  • first_name — String first name of the user
  • last_name — String last name of the user
  • password_confirmation — String password confirmation of the user
  • password — String password of the user
  • roles — Array of string with a valid user role name (user, executor, requestor, deployer, or deployment_coordinator)

Optional attributes

  • contact_number — String contact number for the user
  • max_allocation — Integer max allocation value for the user
  • employment_type — String value (permanent, contractor) for the user
  • time_zone — String value ('Central Time (US & Canada)') for the user
  • first_day_on_calendar — Integer (1-7) for calendar first day for the user

  • app_env_roles — Array of objects with app_id, environment_id, and role attributes for specifying the user custom role for application app_id and its environment environment_id.
    For the example of using app_env_roles for POST requests,  see XML and JSON examples below.

     

Common attributes

  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid.
  • ERROR 422 Unprocessable entity — Occurs when validation fails and objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<user><login>sample_user</login><email>user@example.com</email><first_name>Sample</first_name><last_name>User</last_name><roles type="array"><role>user</role></roles><password>secret</password><password_confirmation>secret</password_confirmation><app_env_roles type="array"><app_env_role><app_id>3</app_id><environment_id>8</environment_id><role>user</role></app_env_role><app_env_roles></user>' http://[rails_host]/v1/users?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"login":"sample_user", "email":"user@example.com", "first_name":"Sample", "last_name":"User", "roles":["requestor"], "password":"secret", "password_confirmation":"secret", "app_env_roles": [{ "app_id":3,"environment_id":8,"role":"user"}]}' http://[rails_host]/v1/users/?token=[api_token]

PUT /v1/users/[id]

Updates an existing user with values from a posted document

Editable attributes

  • active — Boolean value with true for active users and false for inactive users
  • contact_number — String contact number for the user
  • email — String email address for the user
  • employment_type — String value (permanent, contractor) for the user
  • first_day_on_calendar — Integer (1-7) for calendar first day for the user
  • first_name — String first name of the user
  • last_name — String last name of the user
  • login — String for the user login
  • max_allocation — Integer max allocation value for the user
  • password_confirmation — String password confirmation of the user
  • password — String password of the user
  • roles — Array of strings for valid role names (user, requestor, deployer, deployment_coordinator)
  • time_zone — String value for the user (for example, "Central Time (US & Canada)")

  • app_env_roles — Array of objects with app_id, environment_id, and role attributes for specifying the user custom role for application app_id and its environment environment_id.For the example of using app_env_roles for POST requests,  see XML and JSON examples below.

    Note

    The app_environment_roles attribute is available only for BMC Release Process Management version 4.3.01.09 and later.

Common attributes

  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails and objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<user><email>new_email@example.com</email><app_env_roles type="array"><app_env_role><app_id>3</app_id><environment_id>8</environment_id><role>user</role></app_env_role><app_env_roles></user>' http://[rails_host]/v1/users/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "user": { "email" : "new_email@example.com", "app_env_roles": [{ "app_id":3,"environment_id":8,"role":"user"}]}}'  http://[rails_host]/v1/users/[id]?token=[api_token]

DELETE /v1/users/[id]

Makes a user inactive. Sets the active parameter for the user to false.

Common attributes

  • id — Numerical unique ID for record
  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X DELETE http://[rails_host]/v1/users/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/users/[id]?token=[api_token]

Sample output

The following JSON is a sample output from GET /v1/users:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "c18d8d685ef59b085d943df61965cf46"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 7ae70a72aece24779ccbe7ddf61ec756
X-Runtime: 0.627000
Content-Type: application/json;charset=utf-8
Content-Length: 1224
Date: Fri, 26 Oct 2012 07:35:25 GMT

{
    "active": false,
    "admin": false,
    "contact_number": null,
    "created_at": "2014-02-12T06:06:09-05:00",
    "email": "user@example.com",
    "employment_type": "permanent",
    "first_name": "Sample",
    "global_access": false,
    "id": 1,
    "last_name": "User",
    "location": null,
    "login": "new_login",
    "max_allocation": 100,
    "roles": [
        "user"
   ],
    "root": false,
    "system_user": true,
    "time_zone": null,
    "type": null,
    "updated_at": "2014-02-12T06:44:46-05:00",
    "teams": [
        {
            "id": 0,
            "name": "[default]"
        }
    ],
    "groups": [],
    "assigned_environments": [
        {
            "environment_id": 0,
            "id": 103,
            "role": "deployer",
            "environment_name": "[default]",
            "app_id": 0,
            "app_name": "[default]"
        }
    ]
}

The following XML is a sample output from GET /v1/users/1:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "0f6586db4a92d109410481c33dbdef2b"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a06c84aa93782c653643149a22f941a9
X-Runtime: 0.244000
Content-Type: application/xml;charset=utf-8
Content-Length: 2973
Date: Fri, 26 Oct 2012 07:38:13 GMT

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <active type="boolean">true</active>
  <admin type="boolean">false</admin>
  <contact-number>123456</contact-number>
  <created-at type="datetime">2014-02-12T05:40:30-05:00</created-at>
  <email>sample@email.com</email>
  <employment-type>permanent</employment-type>
  <first-name>Sample</first-name>
  <global-access type="boolean">false</global-access>
  <id type="integer">1</id>
  <last-name>User</last-name>
  <location>hq</location>
  <login>sample_user</login>
  <max-allocation type="integer">100</max-allocation>
  <roles type="array">
    <role>user</role>
  </roles>s
  <root type="boolean">false</root>
  <system-user type="boolean">true</system-user>
  <time-zone>Central Time (US &amp; Canada)</time-zone>
  <type nil="true"></type>
  <updated-at type="datetime">2014-02-12T06:16:14-05:00</updated-at>
  <teams type="array">
    <team>
      <id type="integer">0</id>
      <name>[default]</name>
    </team>
  </teams>
  <groups type="array"/>
  <assigned-environments type="array">
    <assigned-environment>
      <environment-id type="integer">0</environment-id>
      <id type="integer">101</id>
      <role>deployer</role>
      <environment-name>[default]</environment-name>
      <app-id type="integer">0</app-id>
      <app-name>[default]</app-name>
    </assigned-environment>
  </assigned-environments>
</user>

Related topic

Administering-users-roles-and-access-permissions

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*