Users

Summary

How to list, create and update users. Deletion is not possible. If you wish to delete a user, remove all his roles. Caution! This user won't be listed anymore.

After creation, the user needs to verify their email-address. An invitation will be sent to the given email-address. As long as the user hasn't confirmed the invitation, they cannot log in.

Please have a look below which attributes are mandatory for creation of a user.

Roles

A role grants specific permissions on Folders/Rooms, Projects and even Clients. You (the API-User) will need the according permission (e.g. "project_admin") to manage users' roles.

A user always needs roles, otherwise, a user will not be visible. Creating a user needs at least one role. "Deleting" a user, means to strip them of all of their roles. There is no DELETE action for the user resource.

To change roles (add, remove) please simply send the new set of roles you wish the user to have. E.g. you want to remove Role A and user has Roles [A,B,C], update the user with Roles [B,C].

Where to find roles

Request of a Folder will now show its roles. You only need to provide the id of the desired role(s). You will have to have the authorization to add roles to the user. E.g. you need to be a "project_admin".

Attributes shown with action GET
company	string
country	string
created_at	datetime
email	string	Mandatory for create. Though, E-Mail cannot be changed over API. Only user themselves may change email using web-interface.
email_assistant	string
first_name	string
id	integer	Use this id to reference to user in the URI.
last_name	string	Mandatory for create.
login	string	Mandatory for create.(Deprecated)
phone	string
position	string
updated_at	datetime

Attributes which can be POSTed
email	string	Mandatory for create. Though, E-Mail cannot be changed over API. Only user themselves may change email using web-interface.
first_name	string
last_name	string	Mandatory for create.
login	string	Mandatory for create.(Deprecated)

Actions
Index	GET	/users	-
Show	GET	/users/{id}	-
Create	POST	/users	body: { "user": { "email": "some@email.com", "roles": [{"id": 1}, {"id": 2}], ... } }
Update	PUT	/users/{id}	body: { "user": { "first_name": "Andrewnow", "roles": [{"id": 1}, {"id": 3}], ... } }
Invite	PATCH	/users/invite	body: { "project_id": 1, "user": { "email": "foo@example.com", "last_name": "Lastname", "roles": [{"id": 1}, {"id": 3}], ... } }
Reset Password	POST	/users/reset_password	body: { "email": "foo@example.com" }

Example

Creating a user

Request:

POST /api/users HTTP/1.1
Authorization: Bearer example-token
Content-Type: application/json
Accept: application/json

{"user": { "last_name":"Kowalski", "login":"pkowalski", "email":"kawumm@film.de", "roles":[{"id":"37"}]}}

Response:

HTTP/1.1 201 Created

{"status":201,"status_message":"Created","info":"An invitation has been sent to created user.",
"data":
  {"user":
    {"aasm_state":"passive",
    "activated_at":null,
    "company":null,
    "country":null,
    "created_at":"2016-08-22T16:26:18+02:00",
    "email":"kawumm@film.de",
    "email_assistant":null,
    "first_name":null,
    "gender": null (deprecated),
    "id":19,
    "last_name":"Kowalski",
    "login":"pkowalski (Deprecated)",
    "phone":null,
    "position":null,
    "updated_at":"2016-08-22T16:26:18+02:00",
    "roles":
      [{"id":37,"item_id":2,"item_type":"Folder","name":"owner"}]
    }
  }
}

Example

Reset Password

Request:

POST /api/users/reset_password HTTP/1.1
Content-Type: application/json
Accept: application/json

{ "email": "foobar@example.com" }

Curl Request:

curl -X POST \
  https://webgate.webgate.io/api/users/reset_password \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{ "email": "foobar@example.com" }'

Response:

HTTP/1.1 200 Ok

{
  "status": 200,
  "status_message": "OK",
  "info": "",
  "data": {
      "hash": {
          "status": "ok"
      }
  }
}