====== 3DM Publisher Admin API - User Management ======

[[publisher_console_api|Back to the index]]

This page describes the user management API's for 3DM Publisher.\\ 
Please familiarize yourself  with [[publisher_console_api_basics|the basics]] first before continuing.

~~INTOC~~

===== Model: User =====

A ''User'' models a well-known user of the server.

Properties: 

^ Property  ^ Required ^ Type  ^ Description  ^
| id | * | number | Unique identifier. |
| username | * | number | Unique name of the user. |
| email |  | number | E-mail address of the user. |
| first_name |  | number | First name of the user. |
| last_name |  | number | Last name of the user. |
| description |  | number | Description of the user. |
| passwordForceChange |  | boolean | User is required to set a new password on first login? | 
| passwordLastModified |  | number | Unix timestamp that was updated on the last password update of the user. |

===== Model: Usergroup =====

A ''Usergroup'' is a list of users.

Properties: 

^ Property  ^ Required ^ Type  ^ Description  ^
| id | * | number | Unique identifier. |
| name | * | number | Name of the group. |
| type |  | ''team'' (default) | Type of the group. |
| user |  | User[] | The list of users that are in this group.\\ Defines a user reference only (an object with only the ''id'' field set) |

===== Operation: List Users =====

=== Discussion ===

This operation retrieves all users.

=== Request ===

''GET'' ''/api/3/user''
  
=== Response (http 200) ===

<code javascript>
[
    {
        "id": 28,
        "username": "test",
        "email": "test@company.com",
        "first_name": "Test",
        "last_name": "User",
        "password": "test123",
        "description": "Test user"
        "language": "english",
        "preferences": "{}",
        "description": "Supportl",
        "passwordLastModified": 1651217754682
    },
    ...
]
</code>

===== Operation: Create User =====

=== Discussion ===

This operation creates a new user account.\\ 
The password can be provided in plain text using the ''password'' field.

Fields: [[#Model: User]]

=== Request ===

''POST'' ''/api/3/user''
  
<code javascript>
{
    "username": "test",
    "email": "test@company.com",
    "first_name": "Test",
    "last_name": "User",
    "password": "test123",
    "passwordForceChange": true,
    "description": "Test user"
}
</code>

=== Response (http 200) ===

<code javascript>
{
    "id": 28,
    "email": "test@company.com",
    "username": "test",
    "first_name": "Test",
    "last_name": "User",
    "language": "english",
    "preferences": "{}",
    "password": "ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae",
    "description": "Test user",
    "passwordForceChange": true,
    "passwordLastModified": 1753874442231
}
</code>

=== Response (http 400) ===

<code javascript>
{
    "code": "field_not_unique",
    "message": "Uniqueness check failed: Another item with this name value 'test' already exists.",
}
</code>

===== Operation: Update User =====

=== Discussion ===

The following fields can be updated: 
  * username
  * email
  * first_name
  * last_name
  * description
  * password
  * passwordForceChange

Fields: see [[#Model: User]]

=== Request ===

''POST'' ''/api/3/user/123''

<code javascript>
{
    "first_name": "John"
}
</code>

=== Response (http 204) ===

//No content//


===== Operation: Delete User =====

=== Discussion ===

This operation deletes an existing user account.

  * Usergroup memberships of the user are removed.
  * Publication permissions for the user are removed.  
  * Publication user bookmarks for the user are removed.

=== Request ===

''DELETE'' ''/api/3/user/123''

=== Response (http 204) ===

//No content//

=== Response (http 404) ===

<code javascript>
{
    "code": "not_found",
    "message": "Delete failed: An item with this id does not exist."
}
</code>
===== Operation: List Usergroups =====

== Discussion ===

This operation retrieves all usergroups.

  * Users in each group are also returned, but only with the ''id'' field filled in.

=== Request ===

''GET'' ''/api/3/usergroup''
  
=== Response (http 200) ===

<code javascript>
[
    {
        "id": 4,
        "name": "TestGroup",
        "description": "description",
        "type": "team",
        "user": [
            {
                "id": 20
            }
        ]
    },
    ...
]
</code>




===== Operation: Create Usergroup =====

=== Discussion ===

This operation creates a new usergroup.

Fields: [[#Model: User Group]]
Fields: [[#Model: User]]

=== Request ===

''POST'' ''/api/3/usergroup''
  
<code javascript>
{
    "name": "TestGroup",
    "description": "description",
    "type": "team",
    "user": [
        {
            "id": 20
        }
    ]
}
</code>

=== Response (http 200) ===

<code javascript>
{
    "id": 4,
    "name": "TestGroup",
    "description": "description",
    "type": "team",
    "user": [
        {
            "id": 20
        }
    ]
}
</code>

=== Response (http 400) ===

<code javascript>
{
    "code": "field_not_unique",
    "message": "Uniqueness check failed: Another item with this name value 'TestGroup' already exists.",
}
</code>


===== Operation: Update Usergroup=====

=== Discussion ===

The following fields can be updated: 
  * name
  * description
  * user

Fields: [[#Model: Usergroup]]\\ 
Fields: [[#Model: User]]

=== Request ===

''POST'' ''/api/3/usergroup/123''

<code javascript>
{
    "name": "Users2",
    "user": [
        {
            "id": 22
        }
    ]
}
</code>

=== Response (http 204) ===

//No content//


===== Operation: Delete Usergroup =====

=== Discussion ===

This operation deletes an existing usergroup.

  * Only the usergroup is deleted, not the users in it.
  * Publication permissions for the usergroup are removed.  

=== Request ===

''DELETE'' ''/api/3/usergroup/123''

=== Response (http 204) ===

//No content//

=== Response (http 404) ===

<code javascript>
{
    "code": "not_found",
    "message": "Delete failed: An item with this id does not exist."
}
</code>