Users management usage

This page explains the usage of the Gatekeeper in managing users.

Anonymous user

Anonynous users are users that do not yet possess a token. Anonymous users can have access to the following APIs.

Action	Verb	Endpoint	Comments
User creation	POST	/api/v3/users	User creation must obviously be done by an anonymous user; the data stored on the user is returned
User login	POST	/api/v3/users/sessions	the user login; the login process, if successfull, returns a token that then turn the user into an authenticated user, when the token is sent with any other request
*	*	*	Any other endpoint or verb used without an authentication token should result in an error being returned (mostly 401 Unauthorized)

Examples

This sub-section lists examples of usage of the above described endpoints.

Creating a user

Creating a user is accomplished by the following request and response.

The request will be something like

$ curl -X POST https://<platform IP address>/api/v3/users \
> -d '{"username":"me", "password":"m3", "name":"My self", "role":"developer", "email":"me@me.com"}' 

The response will be something like

{
  "username":"me",
  "name":"My self",
  "email":"me@me.com",
  "role": {
    "role":"developer",
    "description":"Developer role"
  },
  "status":"active",
  "created_at":"2019-01-29T11:19:00.601Z",
  "updated_at":"2019-01-29T11:19:00.601Z"
}

Logging in

User login can be done like the following.

The request will be something like

$ curl -X POST https://<platform IP address>/api/v3/users/sessions \
> -d '{"username":"me", "password":"m3"}' 

The response will be something like

{
  "token":"eyJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6Im1lIiwibmFtZSI6Ik15IHNlbGYiLCJyb2xlIjoiZGV2ZWxvcGVyIiwiZW1haWwiOiJtZUBtZS5jb20iLCJsb2dpbl90aW1lIjoiMjAxOS0wMS0yOSAxMToyNjo1MyArMDAwMCIsImV4cGlyYXRpb25fdGltZSI6IjIwMTktMDEtMjkgMTI6MjY6NTMgKzAwMDAifQ.EYftj6NEZgsDo1VJpSM30V8FKzze8Ms6RMjHOU6Xg3A"
}

This token is used for authentication in the other endpoints.

Authenticated user

Authenticated users posess a token that they use in each request they do to the API, passing the token in the Authorization HTTP header, as a bearer token.

Action	Verb	Endpoint	Comments
User creation	POST	/api/v3/users	When the user creation is done by an authenticated user and this user plays the role of an admin, the created user can be created also with the admin role; the data stored on the user is returned
User view	GET	/api/v3/users	when the authenticated user has the admin role, all users data is returned; otherwise, only the authenticated user data is returned. The password field is never shown
User update	PATCH	/api/v3/users	Only authenticated users with the role admmin can update other users's data, which includes making them part of the admin role. Users with the other roles can only update their own data
User deletion	DELETE	/api/v3/users	Only authenticated users with the role admmin can delete other users's data. Users with the other roles can only delete their own data.
User logout	DELETE	/api/v3/users/sessions	Logging out means destroying the session that was created by logging in
*	*	*	Any other endpoint or verb used should result in an error being returned (mostely 403 Forbidden)