Users and Roles determine who has access to what data from the API. Roles are defined by regular expressions that determine which hosts the user can see, and what policy outcomes are restricted.

Example: Listing users

Request

code
curl --user admin:admin http://test.cfengine.com/api/user

Response

code
{
  "meta": {
    "page": 1,
    "count": 2,
    "total": 2,
    "timestamp": 1350994249
  },
  "data": [
    {
      "id": "calvin",
      "external": true,
      "roles": [
        "Huguenots", "Marketing"
      ]
    },
    {
      "id": "quinester",
      "name": "Willard Van Orman Quine",
      "email": "noreply@@aol.com",
      "external": false,
      "roles": [
        "admin"
      ]
    }
  ]
}

Example: Creating a new user

All users will be created for the internal user table. The API will never attempt to write to an external LDAP server.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/snookie -X PUT -d
{
  "email": "snookie@mtv.com",
  "roles": [
    "HR"
  ]
}

Response

code
201 Created
}

Example: Updating an existing user

Both internal and external users may be updated. When updating an external users, the API will essentially annotate metadata for the user, it will never write to LDAP. Consequently, passwords may only be updated for internal users. Users may only update their own records, as authenticated by their user credentials.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/calvin -X POST -d '{ "name": "Calvin" }'

Response

code
204 No Content

Example: Retrieving a user

It is possible to retrieve data on a single user instead of listing everything. The following query is similar to issuing GET /api/user?id=calvin, with the exception that the previous query accepts a regular expression for id.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/calvin

Response

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1350994249
  },
  "data": [
    {
      "id": "calvin",
      "name": "Calvin",
      "external": true,
      "roles": [
        "Huguenots", "Marketing"
      ]
    },
  ]
}

Example: Adding a user to a role

Adding a user to a role is just an update operation on the user. The full role-set is updated, so if you are only appending a role, you may want to fetch the user data first, append the role and then update. The same approach is used to remove a user from a role.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/snookie -X POST -d
{
  "roles": [
    "HR", "gcc-contrib"
  ]
}

Response

code
204 No Content
}

Example: Deleting a user

Users can only be deleted from the internal users table.

Request

code
curl --user admin:admin http://test.cfengine.com/api/user/snookie -X DELETE

Response

code
204 No Content