Users API

General notes

Api for operations regarding Users of the application.

Embeddable fields

Name	Type	Description
`roles`	Roles[]	Array of identifiers of related Roles.
`hourly_pays`	HourlyPay[]	Array of related HourlyPays.
`user_group`	UserGroup	Array of related UserGroup.
`notes`	Note	Array of related Notes.
`newest_note`	Note	Newest Note.
`notifications`	Notification[]	Array of related Notifications.
`unread_notifications`	Notification[]	Array of related not readed Notifications.

Content

Users collection:

[POST] create user
[GET] index, searching and filtering users

Single user:

[GET] user detail
[PUT/PATCH] update user
[PUT] update user password
[DELETE] delete user
[POST] change 2fa secret
User's roles:
[GET] user's roles index
[POST] assign user a role
[DELETE] unassign user a role

User's notes:

[GET] user notes index
[POST] create user note

Users collection

Create user

POST /api/v0/users

To set the is_active or roles fields this method needs permission create on users.

Method for creating new User. After user is created, email for account activation is send to given email.

Request

Param	Type	Description	Requirements
`first_name`	string	User's first name	Required. Must be a string with a maximal length of 50 characters.
`last_name`	string	User's last name	Required. Must be a string with a maximal length of 50 characters.
`username`	string	User login username	Required. Must be a string with a maximal length of 50 characters. Must be unique for user.
`email`	string	User email	One of email or phone is required. Must be a valid email address. Must be unique for user.
`is_active`	bool	User's activity flag	Inactive users can not log into e-shop.
`roles`	int[]	Roles	Must be array of unique valid identifiers of existing Roles or empty array.
`google_api_refresh_token`	string	Google Api Refresh Token	Unique token used to generate access tokens.
`google_calendar_id`	string	Google Calendar Id	Specifies user's calendar.

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

{
  "id": 1,
  "first_name": "Ketr",
  "last_name": "Pnotek",
  "email": "ketr.pnotek@mikyhoklubik.cz",
  "phone": "1433223",
  "is_active": true,
  "two_factor_auth_enabled": false,
   "roles": [1],
}

Responses

201 CREATED

New User was successfully created.

POST /api/v0/users HTTP/1.1
Content-Type: application/json
Status-Code: 201

{
  "id": 1,
  "first_name": "Ketr",
  "last_name": "Pnotek",
  "email": "ketr.pnotek@mikyhoklubik.cz",
  "phone": "1433223",
  "is_active": true,
  "user_group_id": null,
  "created_at": "2022-04-13T14:06:00+0200",
  "_links": [
    {
      "href": "/api/v0/users/1",
      "rel": "self",
      "type": "GET"
    }
  ]
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/v0/users HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "5c99f70a-e400-44bb-9cd4-592b0a30e145",
    "errors": [
        {
            "field": "email",
            "message": "The email field is required."
        }
    ]
}

Users index

GET /api/v0/users

This method needs permission read on users.

Get list of existing Users.

Request

Index behaviour	Definition
Paginated by default	Yes
Sorting	`id`, `first_name`, `last_name`, `is_active`, `created_at`, `email`, `phone`
Filters	`id`:enum, `first_name`:string, `last_name`:string, `is_active`:bool, `email`:string, `phone`:string,`role`:array, `created_at`:date

GET /api/v0/users HTTP/1.1

Responses

200 OK

GET /api/v0/users HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "items": [
        {
           "id": 1,
  "first_name": "Ketr",
  "last_name": "Pnotek",
  "email": "ketr.pnotek@mikyhoklubik.cz",
  "phone": "1433223",
  "is_active": true,
  "user_group_id": null,
  "created_at": "2022-04-13T14:06:00+0200",
  "_links": [
    {
      "href": "/api/v0/users/1",
      "rel": "self",
      "type": "GET"
    }
  ]
        }
    ],
    "_meta": {
        "page": 1,
        "total_pages": 1,
        "records": 1,
        "per_page": 100
    }
}

Single user

User detail

GET /api/v0/users/{user_id}

This method needs permission read on users.

Get User detail.

Request

GET /api/v0/users/1 HTTP/1.1

Responses

200 OK

GET /api/v0/users/1 HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
   "id": 1,
  "first_name": "Ketr",
  "last_name": "Pnotek",
  "email": "ketr.pnotek@mikyhoklubik.cz",
  "phone": "1433223",
  "is_active": true,
  "user_group_id": null,
  "created_at": "2022-04-13T14:06:00+0200",
  "_links": [
    {
      "href": "/api/v0/users/1",
      "rel": "self",
      "type": "GET"
    }
  ]
}

404 NOT FOUND

User was not found.

GET /api/v0/users/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

Update user

PUT/PATCH /api/v0/users/{user_id}

This method needs permission update on users.

Method for updating User data.

Request

Param	Type	Description	Requirements
`first_name`	string	User's first name	Required. Must be string of maximal length 50 characters.
`last_name`	string	User's last name	Required. Must be string of maximal length 50 characters.
`email`	string	User email	One of email or phone is required. Must be a valid email address. Must be unique for user.
`phone`	string	User phone number	One of email or phone is required. Must be a valid phone number. Must be unique for user.
`password`	string	User's password	Must be similar to password_confirmation.
`password_confirmation`	string	User's password confirmation	Must be similar to password.
`is_active`	bool	User's activity flag	Inactive users can not log into e-shop.
`two_factor_auth_enabled`	bool	Two factor authentication	Enable or disable two factor authentication
`roles`	int[]	Roles	Present. Must be array of unique valid identifiers of existing Roles or empty array.
`google_api_refresh_token`	string	Google Api Refresh Token	Unique token used to generate access tokens.
`google_calendar_id`	string	Google Calendar Id	Specifies user's calendar.

For PATCH method any field can be omitted.

PUT /api/v0/users/1 HTTP/1.1
Content-Type: application/json

{
  "id": 1,
  "first_name": "Ketr",
  "last_name": "Pnotek",
  "email": "ketr.pnotek@mikyhoklubik.cz",
  "phone": "1433223",
  "user_group_id": 1,
  "is_active": true,
        
  "two_factor_auth_enabled": true
}

Responses

200 OK

User successfully updated.

PUT /api/v0/users/1 HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
  "id": 1,
  "first_name": "Ketr",
  "last_name": "Pnotek",
  "email": "ketr.pnotek@mikyhoklubik.cz",
  "phone": "1433223",
  "is_active": true,
  "user_group_id": 1,
  "two_factor_auth_enabled": true,
  "created_at": "2022-04-13T14:06:00+0200",
  "_links": [
    {
      "href": "/api/v0/users/1",
      "rel": "self",
      "type": "GET"
    }
  ]
}

404 NOT FOUND

User was not found.

PUT /api/v0/users/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

PUT /api/v0/users/1 HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "5c99f70a-e400-44bb-9cd4-592b0a30e145",
    "errors": [
        {
            "field": "first_name",
            "message": "The first name field is required."
        }
    ]
}

Update user password

POST /api/v0/users/{userId}/password-reset-link

Method for updating User data.

Request

Responses

200 OK

404 NOT FOUND

User was not found.

PUT /api/v0/users/2/password-reset-link HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

Delete user

DELETE /api/v0/users/{user_id}

This method needs permission delete on users.

Method for deleting User.

Request

DELETE /api/v0/users/1 HTTP/1.1

Responses

204 NO CONTENT

User successfully deleted.

DELETE /api/v0/users/1 HTTP/1.1
Status-Code: 204

404 NOT FOUND

User was not found.

DELETE /api/v0/users/1 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

Information about two factor authentication

GET /api/v0/users/{user_id}/two-factor

This method shows information about two factor authentication. e.g. Shows google QR code for Google Authenticator

Request

GET /api/v0/users/{user_id}/two-factor HTTP/1.1

Responses

e.g. GoogleAuthenticator

200 OK

GET /api/v0/users/{user_id}/two-factor HTTP/1.1
{
    "qr_code": "<svg xmlns='http://www.w3.org/2000/svg'>....</svg>"
}

401 Unauthorized

GET /api/v0/users/{user_id}/two-factor HTTP/1.1

{
  "type": "Unauthenticated",
  "message": "You must be authenticated for this action.",
  "id": "b78b0367-b209-4a48-b926-9cddbcd04d6b"
}

Verify two factor authentication

This method verifies user's session with two factor authentication

Request

e.g. GoogleAuthenticator

PUT /api/v0/users/{user_id}/two-factor HTTP/1.1

{
    "two_factor_auth_secret": "117852"
}

Responses

e.g. GoogleAuthenticator

200 OK

PUT /api/v0/users/{user_id}/two-factor HTTP/1.1

{
  "id": 90,
  "user_id": 1,
  "client_ip": "172.19.0.1",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
  "access_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzcsInN1YiI6OTAsImV4cCI6MTU5MDk0MTczNCwidHlwIjoidSJ9.08a11c387ed0cb82bc2cd289a2fe3ac8663d7b01ca16952c8dd42598de8ce6b6",
  "refresh_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzgsInN1YiI6OTAsImV4cCI6MTU5MjE0NzczNCwidHlwIjoidSJ9.28a43fd4d578a94b7910e1418815472424a9269028c92d5b50732f4305a7f038",
  "access_expiration_at": "2020-05-31T16:15:34+0000",
  "session_expiration_at": "2020-06-14T15:15:34+0000",
  "two_factor_verified": true,
  "_links": [
    {
      "href": "/api/auth/user-sessions/90",
      "rel": "signout",
      "type": "DELETE"
    }
  ]
}

401 Unauthorized

Provided key is probably invalid.

PUT /api/v0/users/{user_id}/two-factor HTTP/1.1

{
  "type": "TwoFactorUnauthenticated",
  "message": "The key is invalid.",
  "id": "55f5f535-7a2e-42cf-9235-9ac8f15e7fb1" 
}

User notes index

GET /api/v0/users/{user_id}/notes

This method needs permission access on notes.

Get list of existing user Notes.

Request

Index behaviour	Definition
Paginated by default	Yes
Sorting	`id`, `noteable_type`, `noteable_id`, `text`, `user_id`, `created_at`, `updated_at`
Filters	`id`:enum, `noteable_type`:string, `noteable_id`:int, `text`:string, `user_id`:int, `created_at`:date,`updated_at`:date

GET /api/v0/users HTTP/1.1

Responses

200 OK

GET /api/v0/users HTTP/1.1
Content-Type: application/json

{
    "items": [
        {
            "id": 1,
            "noteable_type": "App\\Containers\\Users\\Users\\Models\\User",
            "noteable_id": 2,
            "text": "Note update text",
            "user_id": 1,
            "created_at": "2023-01-05T15:35:48+0100",
            "updated_at": "2023-01-06T11:11:51+0100",
            "_links": [
                {
                    "href": "/api/v0/notes/1",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        },
        {
            "id": 2,
            "noteable_type": "App\\Containers\\Users\\Users\\Models\\User",
            "noteable_id": 2,
            "text": "test poznamky",
            "user_id": 1,
            "created_at": "2023-01-05T15:37:12+0100",
            "updated_at": "2023-01-05T15:37:12+0100",
            "_links": [
                {
                    "href": "/api/v0/notes/2",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ],
    "_meta": {
        "page": 1,
        "total_pages": 1,
        "records": 2,
        "per_page": 100
    }
}

Create user note

POST /api/v0/users/{user_id}/notes

This method needs permission create on notes.

Create user Note.

Request

Param	Type	Description	Requirements
`text`	string	User's first name	Required.
`user_id`	int	Author's User id	Required.

POST /api/v0/users/1/notes HTTP/1.1

{
  "text": "test poznamky"
  "user_id": 2,
}

Responses

200 OK

POST /api/v0/users/1/notes HTTP/1.1
Content-Type: application/json

{
    "id": 9,
    "noteable_type": "App\\Containers\\Users\\Users\\Models\\User",
    "noteable_id": 1,
    "text": "User note test",
    "user_id": 2,
    "created_at": "2023-01-06T12:01:55+0100",
    "updated_at": "2023-01-06T12:01:55+0100",
    "_links": [
        {
            "href": "/api/v0/notes/9",
            "rel": "self",
            "type": "GET"
        }
    ]
}

General notes​

Embeddable fields​

Content​

Users collection

Create user​

POST /api/v0/users

Request​

Responses​

201 CREATED​

422 UNPROCESSABLE ENTITY​

Users index​

GET /api/v0/users

Request​

Responses​

200 OK​

Single user

User detail​

GET /api/v0/users/{user_id}

Request​

Responses​

200 OK​

404 NOT FOUND​

Update user​

PUT/PATCH /api/v0/users/{user_id}

Request​

Responses​

200 OK​

404 NOT FOUND​

422 UNPROCESSABLE ENTITY​

Update user password​

POST /api/v0/users/{userId}/password-reset-link

Request​

Responses​

200 OK​

404 NOT FOUND​

Delete user​

DELETE /api/v0/users/{user_id}

Request​

Responses​

204 NO CONTENT​

404 NOT FOUND​

Information about two factor authentication​

GET /api/v0/users/{user_id}/two-factor

Request​

Responses​

200 OK​

401 Unauthorized​

Verify two factor authentication​

Request​

Responses​

200 OK​

401 Unauthorized​

User notes index​

GET /api/v0/users/{user_id}/notes

Request​

Responses​

200 OK​

Create user note​

POST /api/v0/users/{user_id}/notes

Request​

Responses​

200 OK​

General notes

Embeddable fields

Content

Create user

Request

Responses

201 CREATED

422 UNPROCESSABLE ENTITY

Users index

Request

Responses

200 OK

User detail

Request

Responses

200 OK

404 NOT FOUND

Update user

Request

Responses

200 OK

404 NOT FOUND

422 UNPROCESSABLE ENTITY

Update user password

Request

Responses

200 OK

404 NOT FOUND

Delete user

Request

Responses

204 NO CONTENT

404 NOT FOUND

Information about two factor authentication

Request

Responses

200 OK

401 Unauthorized

Verify two factor authentication

Request

Responses

200 OK

401 Unauthorized

User notes index

Request

Responses

200 OK

Create user note

Request

Responses

200 OK