GET /api/users
List all users

GET /api/auth_source_ldaps/:auth_source_ldap_id/users
List all users for LDAP authentication source

GET /api/auth_source_externals/:auth_source_external_id/users
List all users for external authentication source

GET /api/usergroups/:usergroup_id/users
List all users for user group

GET /api/roles/:role_id/users
List all users for role

GET /api/locations/:location_id/users
List all users for location

GET /api/organizations/:organization_id/users
List all users for organization

Examples

GET /api/users
200
{
  "total": 7,
  "subtotal": 7,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results": [
    {
      "firstname": "Admin",
      "lastname": "User",
      "mail": "admin@someware.com",
      "admin": true,
      "auth_source_id": 200482051,
      "auth_source_name": "Internal",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:04 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 135138680,
      "login": "secret_admin",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [],
      "default_organization": null,
      "organizations": [],
      "effective_admin": true
    },
    {
      "firstname": "apiadmin",
      "lastname": "User",
      "mail": "apiadmin@someware.com",
      "admin": true,
      "auth_source_id": 200482051,
      "auth_source_name": "Internal",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:04 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 886836129,
      "login": "apiadmin",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [],
      "default_organization": null,
      "organizations": [],
      "effective_admin": true
    },
    {
      "firstname": "One",
      "lastname": "User",
      "mail": "userone@someware.com",
      "admin": false,
      "auth_source_id": 980190962,
      "auth_source_name": "ldap-server",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:04 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 980190962,
      "login": "one",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [
        {
          "id": 255093256,
          "name": "Location 1"
        }
      ],
      "default_organization": null,
      "organizations": [
        {
          "id": 447626438,
          "name": "Organization 1"
        }
      ],
      "effective_admin": false
    },
    {
      "firstname": "Restricted",
      "lastname": "User",
      "mail": "userrestricted@someware.com",
      "admin": false,
      "auth_source_id": 980190962,
      "auth_source_name": "ldap-server",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:04 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 130842698,
      "login": "restricted",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [],
      "default_organization": null,
      "organizations": [],
      "effective_admin": false
    },
    {
      "firstname": "Scoped",
      "lastname": "User",
      "mail": "userscoped@someware.com",
      "admin": false,
      "auth_source_id": 980190962,
      "auth_source_name": "ldap-server",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:05 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 117925625,
      "login": "scoped",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [
        {
          "id": 255093256,
          "name": "Location 1"
        }
      ],
      "default_organization": null,
      "organizations": [
        {
          "id": 447626438,
          "name": "Organization 1"
        }
      ],
      "effective_admin": false
    },
    {
      "firstname": "test",
      "lastname": "User",
      "mail": "testuser@someware.com",
      "admin": false,
      "auth_source_id": 200482051,
      "auth_source_name": "Internal",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:04 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 200482051,
      "login": "test",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [],
      "default_organization": null,
      "organizations": [],
      "effective_admin": false
    },
    {
      "firstname": "Two",
      "lastname": "User",
      "mail": "usertwo@someware.com",
      "admin": false,
      "auth_source_id": 980190962,
      "auth_source_name": "ldap-server",
      "timezone": null,
      "locale": null,
      "last_login_on": "2009-10-12 21:50:04 UTC",
      "created_at": "2018-07-24 13:02:47 UTC",
      "updated_at": "2018-07-24 13:02:47 UTC",
      "id": 298486374,
      "login": "two",
      "description": null,
      "ssh_keys": [],
      "default_location": null,
      "locations": [],
      "default_organization": null,
      "organizations": [],
      "effective_admin": false
    }
  ]
}

Params

Param name Description
auth_source_ldap_id
optional

ID of LDAP authentication source

Validations:

  • Must be a String

usergroup_id
optional

ID of user group

Validations:

  • Must be a String

role_id
optional

ID of role

Validations:

  • Must be a String

location_id
optional

Scope by locations

Validations:

  • Must be a Integer

organization_id
optional

Scope by organizations

Validations:

  • Must be a Integer

search
optional

filter results

Validations:

  • Must be a String

order
optional

Sort field and order, eg. ‘id DESC’

Validations:

  • Must be a String

page
optional

paginate results

Validations:

  • Must be a String

per_page
optional

number of entries per request

Validations:

  • Must be a String

Search fields

Field name Type Possible values
admin true, false
description text
firstname string
last_login_on datetime
lastname string
location string
location_id integer
login string
mail string
organization string
organization_id integer
role string
role_id integer
usergroup string

GET /api/users/:id
Show a user

Examples

GET /api/users/one
200
{
  "firstname": "One",
  "lastname": "User",
  "mail": "userone@someware.com",
  "admin": false,
  "auth_source_id": 980190962,
  "auth_source_name": "ldap-server",
  "timezone": null,
  "locale": null,
  "last_login_on": "2009-10-12 21:50:04 UTC",
  "created_at": "2018-07-24 13:02:47 UTC",
  "updated_at": "2018-07-24 13:02:47 UTC",
  "id": 980190962,
  "login": "one",
  "description": null,
  "ssh_keys": [],
  "default_location": null,
  "locations": [
    {
      "id": 255093256,
      "name": "Location 1",
      "title": "Location 1",
      "description": null
    }
  ],
  "default_organization": null,
  "organizations": [
    {
      "id": 447626438,
      "name": "Organization 1",
      "title": "Organization 1",
      "description": null
    }
  ],
  "effective_admin": false,
  "cached_usergroups": [],
  "auth_source_ldap": {
    "id": 980190962,
    "type": "AuthSourceLdap",
    "name": "ldap-server"
  },
  "mail_notifications": [],
  "roles": [
    {
      "name": "Viewer",
      "id": 5,
      "description": null,
      "origin": "foreman"
    }
  ],
  "usergroups": []
}

Params

Param name Description
location_id
optional

Scope by locations

Validations:

  • Must be a Integer

organization_id
optional

Scope by organizations

Validations:

  • Must be a Integer

id
required

Validations:

  • Must be a String


POST /api/users
Create a user

Adds role ‘Default role’ to the user by default

Examples

POST /api/users
{
  "user": {
    "login": "foo",
    "auth_source_id": 200482051,
    "password": "123456",
    "lastname": "OArooQYswI"
  }
}
201
{
  "firstname": null,
  "lastname": "OArooQYswI",
  "mail": null,
  "admin": false,
  "auth_source_id": 200482051,
  "auth_source_name": "Internal",
  "timezone": null,
  "locale": null,
  "last_login_on": null,
  "created_at": "2018-07-24 13:02:50 UTC",
  "updated_at": "2018-07-24 13:02:50 UTC",
  "id": 980190964,
  "login": "foo",
  "description": null,
  "ssh_keys": [],
  "default_location": null,
  "locations": [],
  "default_organization": null,
  "organizations": [],
  "effective_admin": false,
  "cached_usergroups": [],
  "auth_source_internal": {
    "id": 200482051,
    "type": "AuthSourceInternal",
    "name": "Internal"
  },
  "mail_notifications": [],
  "roles": [],
  "usergroups": []
}

Params

Param name Description
location_id
optional

Scope by locations

Validations:

  • Must be a Integer

organization_id
optional

Scope by organizations

Validations:

  • Must be a Integer

user
required

Validations:

  • Must be a Hash

user[login]
required

Validations:

  • Must be a String

user[firstname]
optional , nil allowed

Validations:

  • Must be a String

user[lastname]
optional , nil allowed

Validations:

  • Must be a String

user[mail]
required

Validations:

  • Must be a String

user[description]
optional , nil allowed

Validations:

  • Must be a String

user[admin]
optional , nil allowed

is an admin account

Validations:

  • Must be one of: true, false, 1, 0

user[password]
required

Validations:

  • Must be a String

user[default_location_id]
optional , nil allowed

Validations:

  • Must be a Integer

user[default_organization_id]
optional , nil allowed

Validations:

  • Must be a Integer

user[auth_source_id]
required

Validations:

  • Must be a Integer

user[timezone]
optional , nil allowed

User’s timezone

Validations:

  • Must be one of: American Samoa, International Date Line West, Midway Island, Hawaii, Alaska,

    Maruku could not parse this XML/HTML: 
    <code>Pacific Time (US & Canada)</code>
    , Tijuana, Arizona, Chihuahua, Mazatlan,
    Maruku could not parse this XML/HTML: 
    <code>Mountain Time (US & Canada)</code>
    , Central America,
    Maruku could not parse this XML/HTML: 
    <code>Central Time (US & Canada)</code>
    , Guadalajara, Mexico City, Monterrey, Saskatchewan, Bogota,
    Maruku could not parse this XML/HTML: 
    <code>Eastern Time (US & Canada)</code>
    , Indiana (East), Lima, Quito, Atlantic Time (Canada), Caracas, Georgetown, La Paz, Santiago, Newfoundland, Brasilia, Buenos Aires, Greenland, Montevideo, Mid-Atlantic, Azores, Cape Verde Is., Casablanca, Dublin, Edinburgh, Lisbon, London, Monrovia, UTC, Amsterdam, Belgrade, Berlin, Bern, Bratislava, Brussels, Budapest, Copenhagen, Ljubljana, Madrid, Paris, Prague, Rome, Sarajevo, Skopje, Stockholm, Vienna, Warsaw, West Central Africa, Zagreb, Zurich, Athens, Bucharest, Cairo, Harare, Helsinki, Jerusalem, Kaliningrad, Kyiv, Pretoria, Riga, Sofia, Tallinn, Vilnius, Baghdad, Istanbul, Kuwait, Minsk, Moscow, Nairobi, Riyadh, St. Petersburg, Volgograd, Tehran, Abu Dhabi, Baku, Muscat, Samara, Tbilisi, Yerevan, Kabul, Ekaterinburg, Islamabad, Karachi, Tashkent, Chennai, Kolkata, Mumbai, New Delhi, Sri Jayawardenepura, Kathmandu, Almaty, Astana, Dhaka, Urumqi, Rangoon, Bangkok, Hanoi, Jakarta, Krasnoyarsk, Novosibirsk, Beijing, Chongqing, Hong Kong, Irkutsk, Kuala Lumpur, Perth, Singapore, Taipei, Ulaanbaatar, Osaka, Sapporo, Seoul, Tokyo, Yakutsk, Adelaide, Darwin, Brisbane, Canberra, Guam, Hobart, Melbourne, Port Moresby, Sydney, Vladivostok, Magadan, New Caledonia, Solomon Is., Srednekolymsk, Auckland, Fiji, Kamchatka, Marshall Is., Wellington, Chatham Is., Nuku'alofa, Samoa, Tokelau Is..

user[locale]
optional , nil allowed

User’s preferred locale

Validations:

  • Must be one of: pt_BR, de, it, sv_SE, zh_CN, en_GB, fr, ru, ja, es, ko, ca, gl, en, zh_TW, pl.

user[role_ids]
optional , nil allowed

Validations:

  • Must be an array of any type

user[location_ids]
optional , nil allowed

REPLACE locations with given ids

Validations:

  • Must be an array of any type

user[organization_ids]
optional , nil allowed

REPLACE organizations with given ids.

Validations:

  • Must be an array of any type


PUT /api/users/:id
Update a user

Adds role ‘Default role’ to the user if it is not already present. Only another admin can change the admin account attribute.

Examples

PUT /api/users/980190962
{
  "user": {
    "admin": true
  }
}
200
{
  "firstname": "One",
  "lastname": "User",
  "mail": "userone@someware.com",
  "admin": true,
  "auth_source_id": 980190962,
  "auth_source_name": "ldap-server",
  "timezone": null,
  "locale": null,
  "last_login_on": "2009-10-12 21:50:04 UTC",
  "created_at": "2018-07-24 13:02:47 UTC",
  "updated_at": "2018-07-24 13:02:49 UTC",
  "id": 980190962,
  "login": "one",
  "description": null,
  "ssh_keys": [],
  "default_location": null,
  "locations": [
    {
      "id": 255093256,
      "name": "Location 1",
      "title": "Location 1",
      "description": null
    }
  ],
  "default_organization": null,
  "organizations": [
    {
      "id": 447626438,
      "name": "Organization 1",
      "title": "Organization 1",
      "description": null
    }
  ],
  "effective_admin": true,
  "cached_usergroups": [],
  "auth_source_ldap": {
    "id": 980190962,
    "type": "AuthSourceLdap",
    "name": "ldap-server"
  },
  "mail_notifications": [],
  "roles": [
    {
      "name": "Viewer",
      "id": 5,
      "description": null,
      "origin": "foreman"
    }
  ],
  "usergroups": []
}

Params

Param name Description
location_id
optional

Scope by locations

Validations:

  • Must be a Integer

organization_id
optional

Scope by organizations

Validations:

  • Must be a Integer

id
required

Validations:

  • Must be a String

user
required

Validations:

  • Must be a Hash

user[login]
optional

Validations:

  • Must be a String

user[firstname]
optional , nil allowed

Validations:

  • Must be a String

user[lastname]
optional , nil allowed

Validations:

  • Must be a String

user[mail]
optional

Validations:

  • Must be a String

user[description]
optional , nil allowed

Validations:

  • Must be a String

user[admin]
optional , nil allowed

is an admin account

Validations:

  • Must be one of: true, false, 1, 0

user[password]
optional

Validations:

  • Must be a String

user[default_location_id]
optional , nil allowed

Validations:

  • Must be a Integer

user[default_organization_id]
optional , nil allowed

Validations:

  • Must be a Integer

user[auth_source_id]
optional

Validations:

  • Must be a Integer

user[timezone]
optional , nil allowed

User’s timezone

Validations:

  • Must be one of: American Samoa, International Date Line West, Midway Island, Hawaii, Alaska,

    Maruku could not parse this XML/HTML: 
    <code>Pacific Time (US & Canada)</code>
    , Tijuana, Arizona, Chihuahua, Mazatlan,
    Maruku could not parse this XML/HTML: 
    <code>Mountain Time (US & Canada)</code>
    , Central America,
    Maruku could not parse this XML/HTML: 
    <code>Central Time (US & Canada)</code>
    , Guadalajara, Mexico City, Monterrey, Saskatchewan, Bogota,
    Maruku could not parse this XML/HTML: 
    <code>Eastern Time (US & Canada)</code>
    , Indiana (East), Lima, Quito, Atlantic Time (Canada), Caracas, Georgetown, La Paz, Santiago, Newfoundland, Brasilia, Buenos Aires, Greenland, Montevideo, Mid-Atlantic, Azores, Cape Verde Is., Casablanca, Dublin, Edinburgh, Lisbon, London, Monrovia, UTC, Amsterdam, Belgrade, Berlin, Bern, Bratislava, Brussels, Budapest, Copenhagen, Ljubljana, Madrid, Paris, Prague, Rome, Sarajevo, Skopje, Stockholm, Vienna, Warsaw, West Central Africa, Zagreb, Zurich, Athens, Bucharest, Cairo, Harare, Helsinki, Jerusalem, Kaliningrad, Kyiv, Pretoria, Riga, Sofia, Tallinn, Vilnius, Baghdad, Istanbul, Kuwait, Minsk, Moscow, Nairobi, Riyadh, St. Petersburg, Volgograd, Tehran, Abu Dhabi, Baku, Muscat, Samara, Tbilisi, Yerevan, Kabul, Ekaterinburg, Islamabad, Karachi, Tashkent, Chennai, Kolkata, Mumbai, New Delhi, Sri Jayawardenepura, Kathmandu, Almaty, Astana, Dhaka, Urumqi, Rangoon, Bangkok, Hanoi, Jakarta, Krasnoyarsk, Novosibirsk, Beijing, Chongqing, Hong Kong, Irkutsk, Kuala Lumpur, Perth, Singapore, Taipei, Ulaanbaatar, Osaka, Sapporo, Seoul, Tokyo, Yakutsk, Adelaide, Darwin, Brisbane, Canberra, Guam, Hobart, Melbourne, Port Moresby, Sydney, Vladivostok, Magadan, New Caledonia, Solomon Is., Srednekolymsk, Auckland, Fiji, Kamchatka, Marshall Is., Wellington, Chatham Is., Nuku'alofa, Samoa, Tokelau Is..

user[locale]
optional , nil allowed

User’s preferred locale

Validations:

  • Must be one of: pt_BR, de, it, sv_SE, zh_CN, en_GB, fr, ru, ja, es, ko, ca, gl, en, zh_TW, pl.

user[role_ids]
optional , nil allowed

Validations:

  • Must be an array of any type

user[location_ids]
optional , nil allowed

REPLACE locations with given ids

Validations:

  • Must be an array of any type

user[organization_ids]
optional , nil allowed

REPLACE organizations with given ids.

Validations:

  • Must be an array of any type

user[current_password]
optional , nil allowed

Required when user want to change own password

Validations:

  • Must be a String


DELETE /api/users/:id
Delete a user

Examples

DELETE /api/users/980190962
{
  "user": {}
}
200
{
  "id": 980190962,
  "login": "one",
  "firstname": "One",
  "lastname": "User",
  "mail": "userone@someware.com",
  "admin": false,
  "last_login_on": "2009-10-12T21:50:04.000Z",
  "auth_source_id": 980190962,
  "created_at": "2018-07-24T13:02:47.515Z",
  "updated_at": "2018-07-24T13:02:47.515Z",
  "password_hash": null,
  "password_salt": null,
  "locale": null,
  "avatar_hash": null,
  "default_organization_id": null,
  "default_location_id": null,
  "lower_login": "one",
  "mail_enabled": true,
  "timezone": null,
  "description": null,
  "password": null
}

Params

Param name Description
location_id
optional

Scope by locations

Validations:

  • Must be a Integer

organization_id
optional

Scope by organizations

Validations:

  • Must be a Integer

id
required

Validations:

  • Must be a String