# Roles & Permissions Stores the information of the users via the Omnitron application. There are two types of users on Omnitron: * Super User * Staff ## User Types * **Super User** These users can view all the menus and take all kinds of actions in the Omnitron application. They are controlled with the `is_superuser` field in the User model. * **Staff** Users can view Omnitron menus depending on the authorization groups. They are controlled with the is\_staff field in the User model. ## User Property Fields There are mandatory and optional user property fields: **Mandatory Fields** * Username * The user’s username on the Omnitron application. Must be unique. * Must be 150 characters or less. Only accepts letters, numbers and “@.+-\_” characters. * Name * Surname * Email * Password **Optional Fields** * General Authorization Groups * Determines the menus, buttons, etc., on the Omnitron interface visible to users who have been defined as staff. * Catalog Authorization Group * Determines the categories visible to the user. * Channel Authorization Group * Determines the sales channels visible to the user in the “Sales Channels” menu. * Phone * Avatar * Super User * The variable that grants the user full authority on the Omnitron interface. * Grants access to all menus regardless of authorization groups. * Staff * Normal users. The menus visible to these users in the Omnitron software depends on the authorization groups. * Active/Inactive * If the user is inactive, they are prevented from logging into the Omnitron software. ## Serializer This serializer is used for data validation and representation for the request/response life cycle. Contains particular fields in addition to the Django auth user model. * `username`: Unique identifier of the user. * `first_name`: Name. * `last_name`: Surname. * `email`: Email address. * `is_staff`: The boolean value for staff indication. * `is_superuser`: The boolean value for super user indication. * `is_active`: Activation status. * `groups`: User authorization groups. Their PK value reflects the Django auth group model. It can take multiple values. * `date_joined`: Registration date. * `last_login`: Date value of the last successful login. ## ViewSet | **Endpoints** | | ------------------------- | | /api/v1/users/ | | {\`/api/v1/users/{pk}/\`} | **Allowed HTTP Requests:** * GET * POST * PUT * PATCH * DELETE **Potential Responses:** * 200 OK * 201 Created * 204 No Content * 400 Bad Request * 401 Unauthorized * 404 Not Found * 406 Not Acceptable ### `GET` Users This endpoint can be used to retrieve all users as a list. Path: `/api/v1/users/` **Response** ```json { "count": 1, "next": null, "previous": null, "results": [ { "pk": 1, "username": "foo", "first_name": "bar", "last_name": "baz", "email": "qux@akinon.com", "is_staff": true, "is_active": true, "date_joined": "2022-12-21T10:32:51.707174Z", "last_login": "2022-12-21T12:21:30.684071Z", "is_superuser": true, "groups": [1, 2, 3] }, … ] } ``` ### `GET` User Search This endpoint can be used to retrieve all users that match the given search parameters as a list. Path: `/api/v1/users/?pk__in={user_pk},{user_pk},{user_pk}&is_admin={true|false}&is_staff={true|false}&username={username}&email={user_email}&first_name={first_name}&last_name={last_name}` | **Parameter** | **Description** | | ------------- | ------------------------------------------------------------------------------------- | | pk\_\_in | Permits fetching users with a known PK | | is\_admin | Permits the filtering of admin users and normal users | | is\_staff | Permits the filtering of staff users and normal users | | username | Queries whether there are any registered users associated with the given username | | first\_name | Queries whether there are any registered users associated with the given first\_name | | last\_name | Queries whether there are any registered users associated with the given last\_name | | email | Queries whether there are any registered users associated with the sent email address | **Response** ```json { "count": 1, "next": null, "previous": null, "results": [ { "pk": 1, "username": "foo", "first_name": "bar", "last_name": "baz", "email": "qux@akinon.com", "is_staff": true, "is_active": true, "date_joined": "2022-12-21T10:32:51.707174Z", "last_login": "2022-12-21T12:21:30.684071Z", "is_superuser": true, "groups": [1, 2, 3] }, … ] } ``` ### **`GET` User Detail​** This endpoint can be used to retrieve a user that is paired with the given {PK} value. Path: `/api/v1/users/{PK}/` **Response** ```json { "pk": 1, "username": "foo", "first_name": "bar", "last_name": "baz", "email": "qux@akinon.com", "is_staff": true, "is_active": true, "date_joined": "2022-12-21T10:32:51.707174Z", "last_login": "2022-12-21T12:21:30.684071Z", "is_superuser": true, "groups": [1, 2, 3] } ``` ### `POST` Create User This endpoint can create a new user according to the input. According to the serializer section the following input model must be used. | **Field** | **Type** | **Mandatory** | **Default** | | ------------- | ----------------- | ------------- | ----------- | | username | string | Yes | N/A | | password | string**\*** | Yes | N/A | | email | string | Yes | N/A | | groups | list(integer) | Yes | N/A | | first\_name | string | No | None | | last\_name | string | No | None | | is\_active | boolean | No | True | | is\_staff | boolean | No | False | | is\_superuser | boolean | No | False | **Note:** Password is required to have at least eight characters, including a capital letter, a number, and a special character. Path: `/api/v1/users/` ```json { "username": "foo", "password": "Bar123*!", "email": "baz@akinon.com", "groups": [1, 2, 3] } ``` **Response** ```json { "pk": 2, "username": "foo", "first_name": "", "last_name": "", "email": "baz@akinon.com", "is_staff": false, "is_active": true, "date_joined": "2022-12-21T09:15:38.123104Z", "last_login": null, "is_superuser": false, "groups": [1, 2, 3] } ``` ### `PATCH` Update User This endpoint can partially update a user according to the input. According to the serializer section the following input model must be used. | **Field** | **Type** | **Mandatory** | **Default** | | ------------- | ----------------- | ------------- | ----------- | | username | string | No | N/A | | password | string**\*** | No | N/A | | email | string | No | N/A | | groups | list(integer) | No | N/A | | first\_name | string | No | None | | last\_name | string | No | None | | is\_active | boolean | No | True | | is\_staff | boolean | No | False | | is\_superuser | boolean | No | False | **Note:** Password is required to have at least eight characters, including a capital letter, a number, and a special character. Path: `/api/v1/users/{pk}/` ``` { "is_superuser": true, "is_active": false } ``` **Response** ```json { "pk": 2, "username": "foo", "first_name": "", "last_name": "", "email": "baz@akinon.com", "is_staff": true, "is_active": false, "date_joined": "2022-12-21T09:15:38.123104Z", "last_login": null, "is_superuser": true, "groups": [1, 2, 3] } ``` ### `PUT` Update User This endpoint can update a user according to the input. According to the serializer section this input model must be used. Path: `/api/v1/users/{pk}/` ```json { "username": "foo", "first_name": "qux", "password": "Bar123*!", "email": "baz@akinon.com", "groups": [1, 2, 3] } ``` **Response** ```json { "pk": 2, "username": "foo", "first_name": "qux", "last_name": "", "email": "baz@akinon.com", "is_staff": true, "is_active": false, "date_joined": "2022-12-21T09:15:38.123104Z", "last_login": null, "is_superuser": true, "groups": [1, 2, 3] } ``` ### `DELETE` User Path: `/api/v1/users/{pk}/` It does not permanently delete the user. It changes `is_active` value to False. **Response** 204: No Content.