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 — Unique numerical ID for the 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 the 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

  • email — String email address 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
  • password_confirmation — String password confirmation of the user
  • password — String password of the user

Optional attributes

  • contact_number — String contact number for the user
  • employment_type — String value for the user's type of employment (for example, permanent or contractor)
  • first_day_on_calendar — Integer (1-7) for the user's first calendar day
  • group_ids — Unique numerical value that identifies a group
  • max_allocation — Integer max allocation value for the user
  • time_zone — String value for the time zone of the user (for example, 'Central Time (US & Canada)')

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; 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><first_name>Sample</first_name><last_name>User</last_name><email>user@example.com</email><login>sample_user</login><password>secret</password><password_confirmation>secret</password_confirmation><group_ids>1</group_ids></user>'
http://[rails_host]/v1/users?token=[api_token]
curl -i -H "accept: application/json" -H
"Content-type: application/json" -X POST -d '{"email":"user@example.com",
"first_name":"Sample","last_name":"User","login":"sample_user","password":"secret","password_confirmation":"secret","group_ids":1}'
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 for the user's type of employment (for example, permanent or contractor)
  • first_day_on_calendar — Integer (1-7) for the user's first calendar day
  • first_name — String first name of the user
  • group_ids — Unique numerical value that identifies a group
  • 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
  • time_zone — String value for the time zone of the user (for example, 'Central Time (US & Canada)')

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 the record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails; 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><group_ids>1</group_ids>’
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", "group_ids":1}}'
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 — Unique numerical ID for the 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 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": true,
     "admin": false,
     "contact_number": "",
     "created_at": "2012-04-30T20:00:00-04:00",
     "email": "user_01@ex.com",
     "employment_type": "permanent",
     "first_name": "John",
     "global_access": false,
     "id": 1,
     "last_name": "Administrator",
     "location": "New York",
     "login": "admin",
     "max_allocation": 100,
     "system_user": true,
     "time_zone": "Eastern Time (US & Canada)",
     "type": null,
     "updated_at": "2015-09-24T07:51:49-04:00",
     "teams": [],
     "groups": [
         {
             "id": 20,
             "name": "Coordinator Group"
         },
         {
             "id": 30,
             "name": "Root"
         },
         {
             "id": 25,
             "name": "Coordinator Admin Group"
         },
         {
             "id": 29,
             "name": "Site Admin Group"
         }
    ]
 }

The following XML is 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></contact-number>
 <created-at type="datetime">2012-04-30T20:00:00-04:00</created-at>
 <email>user_01@ex.com</email>
 <employment-type>permanent</employment-type>
 <first-name>John</first-name>
 <global-access type="boolean">false</global-access>
 <id type="integer">1</id>
 <last-name>Administrator</last-name>
 <location>New York</location>
 <login>admin</login>
 <max-allocation type="integer">100</max-allocation>
 <system-user type="boolean">true</system-user>
 <time-zone>Eastern Time (US &amp; Canada)</time-zone>
 <type nil="true"/>
 <updated-at type="datetime">2015-09-24T05:16:00-04:00</updated-at>
 <teams type="array"/>
 <groups type="array">
   <group>
     <id type="integer">20</id>
     <name>Coordinator Group</name>
   </group>
   <group>
     <id type="integer">30</id>
     <name>Root</name>
   </group>
   <group>
     <id type="integer">25</id>
     <name>Coordinator Admin Group</name>
   </group>
   <group>
     <id type="integer">29</id>
     <name>Site Admin Group</name>
   </group>
 </groups>
</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*