> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/omnitron/user-management/roles-and-permissions.md). # 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidocs.akinon.com/omnitron/user-management/roles-and-permissions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.