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
aasm_state string pending: User was successfully created and sent an invitation.
active: User confirmed his email-address and completed the registration process.
passive: User deactivated.
activated_at datetime
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.
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.
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 send 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",
    "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.de/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"
      }
  }
}