<!-- Source: https://docs.squirro.com/en/latest/api/squirro_client.user.UserApiMixin.html -->
# UserApiMixin

**`class UserApiMixin`**

Bases: [`object`](https://docs.python.org/3.11/library/functions.html#object)

Mixin class which encapsulates the functionality of the user API
service.

All the methods of this class are made available in the
[[SquirroClient]] class.

Methods SummaryMethods Documentation

**`add_group_member(group_id, user_id)`**

Adds a user to the group.

Parameters

- `group_id` – Identifier of the group to add the user to.
- `user_id` – Identifier of the user to add to the group.

Example:

```
>>> client.add_group_member('1jo-WmmyRvC8UYtPMIQaoQ',
                            'H5Qv-WhgSBGW0WL8xolSCQ')
{
    u'email': u'user01@example.com',
    u'full_name': u'User 1',
    u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
    u'role': u'user',
    u'role_permissions': [u'user'],
    u'tenant': 'lW8-FnZlQYWBimxFknYitw'
}
```

**`add_project_member(project_id, role, user_id=None, group_id=None)`**

Adds a user or group to a project as a member.

Parameters

- `project_id` – Project identifier of the project in which to add
  the member.
- `role` – Role of the member. Allowed values: reader, member,
  admin.
- `user_id` – Identifier of the user to be added (can’t be combined
  with group_id).
- `group_id` – Identifier of the group to be added (can’t be
  combined with user_id).

Example:

```
>>> client.add_project_member('2sic33jZTi-ifflvQAVcfw', 'member',
                              user_id='H5Qv-WhgSBGW0WL8xolSCQ')
{
   u'email': u'user01@example.com',
   u'full_name': u'User 1',
   u'member_id': u'H5Qv-WhgSBGW0WL8xolSCQ',
   u'member_type': u'user',
   u'server_role': u'user',
   u'project_role': u'member',
   u'project_id': '2sic33jZTi-ifflvQAVcfw'
   u'permissions': [
                    u'items.*',
                    u'previews.*',
                    u'projects.read.*',
                    u'projects.write.*',
                    u'savedsearches.*',
                    u'scores.*',
                    u'signals.*',
                    u'sources.*']
}
```

**`add_user(email=None, password=None, role=None)`**

Add a new user to the current tenant.

Parameters

- `email` – Email address of the user.
- `password` – Password of the user.
- `role` – role of the user in the tenant. Must be one of:
  admin, user, demo, reader

**`add_workspace_users(workspace_domain, emails, role)`**

Adds users to a workspace by email address.

Example:

```
>>> client.add_workspace_users(
...     "project-1", ["user@example.com", "foo@example.com"], "reader")
[
    {"user_id": "wWzKOdx-TiiPV2k7FEu6_w", "workspace": "project-1"},
    {"user_id": "8Mavps2oTSatzomVEEBtVA", "workspace": "project-1"}
]
```

**`change_user_password(user_id, current_password, new_password, new_password_confirm)`**

Change a user’s password.

Parameters

- `user_id` – User identifier.
- `current_password` – User’s current password.
- `new_password` – User’s new password.
- `new_password_confirm` – User’s new password for confirmation.

**`create_group(name, members=None)`**

Create a new group.

Parameters

- `name` – Group name
- `members` – List of members that should be added to the group.
  This is a list of dictionaries, where only the id field is used
  for each entry.

Example:

```
>>> client.create_group('Team East', members=[{"id": "5efzuNRpQ266E3O11b0h2w"}])
{
    'id': '1jo-WmmyRvC8UYtPMIQaoQ',
    'name': 'Team East',
    'members': [
      {
          'email': 'user01@example.com',
          'full_name': 'User 1',
          'id': '5efzuNRpQ266E3O11b0h2w',
          'role': 'user',
          'role_permissions': ['user'],
          'tenant': 'lW8-FnZlQYWBimxFknYitw'
      }
  ]
}
```

**`create_workspace(title)`**

Create a new workspace.

Parameters

`title` – Workspace title.

Example:

```
>>> client.create_workspace(title="Project 5")
{"domain": "project-5", "title": "Project 5"}
```

**`delete_authentication(user_id, service)`**

Delete an authentication.

Parameters

- `user_id` – User identifier.
- `service` – Service name.

Example:

```
>>> client.delete_authentication('H5Qv-WhgSBGW0WL8xolSCQ',
...                              'facebook')
```

**`delete_grant(user_id, grant_id)`**

Delete a grant.

Parameters

- `user_id` – User identifier.
- `grant_id` – Grant identifier.

Example:

```
>>> client.delete_grant(
...     'H5Qv-WhgSBGW0WL8xolSCQ', 'yL0dnd17RNe9Jpn7uAa8Bw')
```

**`delete_group(group_id)`**

Delete a group.

Parameters

`group_id` – Identifier of the group to delete.

Example:

```
>>> client.delete_group('1jo-WmmyRvC8UYtPMIQaoQ')
```

**`delete_group_member(group_id, user_id)`**

Removes a user from the group.

Parameters

- `group_id` – Identifier of the group from which to remove the user.
- `user_id` – Identifier of the user to remove from the group.

Example:

```
>>> client.delete_group_member('1jo-WmmyRvC8UYtPMIQaoQ',
                               'H5Qv-WhgSBGW0WL8xolSCQ')
```

**`delete_project_member(project_id, member_id)`**

Removes a user or group from a project as a member.

Parameters

- `project_id` – Project identifier of the project to remove the
  member from.
- `member_id` – Identifier of the user or group to be removed.

Example:

```
>>> client.delete_project_member('2sic33jZTi-ifflvQAVcfw',
                                 'H5Qv-WhgSBGW0WL8xolSCQ')
```

**`delete_session(user_id, session_id)`**

Delete a session.

Parameters

- `user_id` – User identifier.
- `session_id` – Session identifier

Example:

```
>>> client.delete_session('H5Qv-WhgSBGW0WL8xolSCQ',
...                       'yL0dnd17RNe9Jpn7uAa8Bw')
```

**`delete_user(user_id)`**

Delete a user from the system.

Parameters

`user_id` – Identifier of the user to delete.

Example:

```
>>> client.delete_user('H5Qv-WhgSBGW0WL8xolSCQ')
```

**`delete_workspace(workspace_domain)`**

Delete a workspace.

Example:

```
>>> client.delete_workspace("workspace-1")
```

**`delete_workspace_user(workspace_domain, user_id)`**

Delete a user from the workspace.

Example:

```
>>> client.delete_workspace_user("project-1", "wWzKOdx-TiiPV2k7FEu6_w")
>>>
```

**`get_authentication(user_id, service)`**

Retrieves an authentication for a given service.

Parameters

- `user_id` – User identifier
- `service` – Authentication service

Returns

A dictionary containing the authentication data.

Example:

```
>>> client.get_authentication('H5Qv-WhgSBGW0WL8xolSCQ', 'facebook')
{u'access_secret': u'secret',
 u'access_secret_expires': u'2014-01-09T08:40:00',
 u'access_token': u'token',
 u'access_token_expires': u'2014-01-09T08:40:00',
 u'display_name': u'John Smith',
 u'service_user': u'1234567',
 u'state': u'ok'}
```

**`get_group(group_id, include_projects=False)`**

Returns details, including the members, of a group.

Parameters

- `group_id` – Identifier of the group for which the details are
  returned.
- `include_projects` – Include all projects the group has access to.

Example:

```
>>> client.get_group('1jo-WmmyRvC8UYtPMIQaoQ')
{
    u'id': u'1jo-WmmyRvC8UYtPMIQaoQ',
    u'name': 'Team East',
    u'members': [
        {
            u'email': u'user01@example.com',
            u'full_name': u'User 1',
            u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
            u'role': u'user',
            u'role_permissions': [u'user'],
            u'tenant': 'lW8-FnZlQYWBimxFknYitw'
        }
    ]
}
```

**`get_groups()`**

Returns all groups within the logged-in users tenant.

Example:

```
>>> client.get_groups()
[{u'id': u'1jo-WmmyRvC8UYtPMIQaoQ',
  u'name': 'Team East',
  u'members': [
      {
          u'email': u'user01@example.com',
          u'full_name': u'User 1',
          u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
          u'role': u'user',
          u'role_permissions': [u'user'],
          u'tenant': 'lW8-FnZlQYWBimxFknYitw'
      }
  ]
 }
]
```

**`get_project_members(project_id)`**

Returns all users and groups associated with the given project.

Parameters

`project_id` – Project identifier.

Example:

```
>>> client.get_project_members('2sic33jZTi-ifflvQAVcfw')
{u'members': [{
   u'email': u'user01@example.com',
   u'full_name': u'User 1',
   u'member_id': u'H5Qv-WhgSBGW0WL8xolSCQ',
   u'member_type': u'user',
   u'server_role': u'user',
   u'project_role': u'reader',
   u'project_id': '2sic33jZTi-ifflvQAVcfw'
   u'permissions': [
                    u'items.read.*',
                    u'previews.read.*',
                    u'projects.read.*',
                    u'savedsearches.read.*',
                    u'scores.read.*',
                    u'signals.read.*',
                    u'sources.read.*']},
    …
]}
```

The permissions list reflects the permissions the given user or group
has in this project. The permissions depend on the user’s project role
and server role.

**`get_session(user_id, session_id)`**

Get data of a specific session.

Parameters

- `user_id` – User identifier.
- `session_id` – Session identifier

Example:

```
>>> client.get_session('H5Qv-WhgSBGW0WL8xolSCQ', 'yL0dnd17RNe9Jpn7uAa8Bw')
```

**`get_token_from_msexchuid(msexchuid)`**

**Retrieves the OAUTH2 authentication token for a given user based**

on their MS Exchange UID (if it exists).

Parameters

`msexchuid` – Microsoft Exchange UID

Returns

A dictionary containing the OAUTH2 token and the Squirro user id.

Example:

```
>>> client.get_token_from_msexchuid('89edf14d-90c4-834d-9efc-cd20a93fc74b')
{
    u'oauth2_token': u'5ad37930dda85a7...6c066b2253dba8d19',
    u'user_id': u'vP7h4g7EThuJKIfMorHTUQ',
}
```

**`get_token_from_msexchuid_token(msexchuid_token)`**

Retrieves an OAUTH2 authentication token based on the provided MS Exchange user
identity token.

Parameters

`msexchuid_token` – a Microsoft Exchange user identity token (JWT).

Returns

A dictionary containing the OAUTH2 token and the Squirro user id.

Example:

```
>>> client.get_token_from_msexchuid_token("<your.jwt.token>")
{
    u'oauth2_token': u'5ad37930dda85a7...6c066b2253dba8d19',
    u'user_id': u'vP7h4g7EThuJKIfMorHTUQ',
}
```

**`get_user_data(user_id, include_projects=False, api_version='v1')`**

Return data about a specific user, including any custom values.

Parameters

- `user_id` – User identifier.
- `include_projects` – Return a list of all the user’s projects.
- `api_version` – The version of the API to use (optional).

Returns

A dictionary which contains the user data.

Example:

```
>>> client.get_user_data('H5Qv-WhgSBGW0WL8xolSCQ')
{u'email': u'test@test.com',
 u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
 u'tenant': u'test'}
```

**`get_user_grants(user_id)`**

Get all grants for the provided user.

Parameters

`user_id` – User identifier.

Returns

A dictionary where the value of grants is a list of the
grants.

Example:

```
>>> client.get_user_grants('H5Qv-WhgSBGW0WL8xolSCQ')
{u'grants': [{u'created_at': u'2012-12-21 16:00:01',
              u'valid_to': u'2022-12-21 16:00:01',
              u'id': u'yL0dnd17RNe9Jpn7uAa8Bw', u'type': u'user'}]}
```

**`get_users(include_config=None)`**

Returns all users within the logged-in users tenant.

Parameters

`include_config` – Boolean Whether to include user configuration or
not. Defaults to True

Example:

```
>>> client.get_users()
{u'users': [
    {
        u'email': u'user01@example.com',
        u'full_name': u'User 1',
        u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
        u'role': u'user',
        u'role_permissions': [u'user'],
        u'tenant': u'lW8-FnZlQYWBimxFknYitw',
        …
    }
]}
```

**`get_users_password_policy()`**

Retrieve the password policy for users’ passwords.

**`get_workspace_users(workspace_domain)`**

Returns a list of all users from a workspace.

Example:

```
>>> client.get_workspace_users("project-1")
[
    {"id": "wWzKOdx-TiiPV2k7FEu6_w",
     "email": "user@example.com",
     "role": "admin",
     "full_name": "User Example"}
]
```

**`get_workspaces(include_projects=False, admin_only=False)`**

Returns a list of all the workspaces the user can access.

Parameters

- `include_projects` – Include all projects the user has access to.
- `admin_only` – If set to True only return workspaces on which
  the user is an admin.

Example:

```
>>> client.get_workspaces()
[
    {
        "domain": "other-project",
        "title": "Other Project"
    },
    {
        "domain": "project-1",
        "title": "Project 1"
    }
]
```

**`new_grant(user_id, type, for_client_id=None, project_permissions=None)`**

Create a new grant.

Parameters

- `user_id` – User identifier.
- `type` – Token type, either user or service.
- `for_client_id` – Client id of the service the token is for. Only
  used when type is service.
- `project_permissions` – List of permissions granted with this
  grant (e.g. `['items.*', 'projects.read.*']`).

Returns

A dictionary containing the refresh_token and the id of
the grant.

Example:

```
>>> client.new_grant('H5Qv-WhgSBGW0WL8xolSCQ', 'service',
...                  'abdc0183029498f20c38',
...                  project_permissions=['items.*', 'projects.read.*'])
{u'id': u'yL0dnd17RNe9Jpn7uAa8Bw',
 u'refresh_token': u'b4c7440364afb80c2...14e2d538b0b773894ea2'}
```

**`new_or_modify_authentication(user_id, service, service_user, access_token, access_secret=None, display_name=None, access_token_expires=None, access_secret_expires=None)`**

Create a new authentication or modify an existing authentication
for an external service.

Parameters

- `user_id` – User identifier.
- `service` – Authentication service.
- `service_user` – Service user identifier.
- `access_token` – Service access token.
- `access_secret` – Service access secret.
- `display_name` – Service user display name.
- `access_token_expires` – Expiry date for service access token.
- `access_secret_expires` – Expiry date for service access secret.

Returns

A dictionary containing the updated authentication data.

Example:

```
>>> client.new_or_modify_authentication(
...     'H5Qv-WhgSBGW0WL8xolSCQ', 'facebook', '1234567', 'token',
...     'secret', 'John Smith',
...     datetime.datetime(2014, 1, 9, 8, 40),
...     datetime.datetime(2014, 1, 9, 8, 40))
{u'access_secret': u'secret',
 u'access_secret_expires': u'2014-01-09T08:40:00',
 u'access_token': u'token',
 u'access_token_expires': u'2014-01-09T08:40:00',
 u'display_name': u'John Smith',
 u'service_user': u'1234567',
 u'state': u'ok'}
```

**`resolve_workspace(workspace_identifier)`**

Resolve a workspace by domain or title, returning the domain.

Tries exact domain match first, then case-insensitive title match.

Parameters

`workspace_identifier` – Workspace domain or title.

Returns

The workspace domain string.

Raises

`NotFoundError` – If no matching workspace is found.

Example:

```
>>> client.resolve_workspace("Workspace Five")
"workspace-5"
>>> client.resolve_workspace("workspace-5")
"workspace-5"
```

**`set_workspace_user_role(workspace_domain, user_id, role)`**

Adds or edits a user’s role in a workspace.

Example:

```
>>> client.set_workspace_user_role(
...     "project-1", "wWzKOdx-TiiPV2k7FEu6_w", "admin")
{"user_id": "wWzKOdx-TiiPV2k7FEu6_w", "workspace": "project-1"}
```

**`signup(email, password, full_name=None)`**

Create the first user on the cluster or create a new workspace.

This implements two different cases depending on the cluster
configuration:

- With workspaces enabled, the user is created in the global workspace,
  but only if no existing user exists there. If a user has already
  been created in the global tenant, signup always fails.
- Without workspaces, a new tenant is created for that user. This is
  a legacy feature, re-implementing the original multi-tenancy
  approach. This may be changed in the future to only allow a signup
  if no tenant/user has been created yet.

Parameters

- `email` – Email address for the user.
- `password` – Password for the user.
- `full_name` – Display name for the user.

Returns

A dictionary which contains the user data.

Example:

```
>>> client.signup(email='foo@example.com', password='aSKJL18274!')
{'user_id': 'ixLkdYmaQzasRi5_luj7IQ',
 'tenant': 'example'}
```

**`update_group(group_id, name, members=None, projects=None)`**

Modify a group’s attributes.

Parameters

- `group_id` – Identifier of the group to modify.
- `name` – New name of the group.
- `members` – List of members that should be added to the group.
  This is a list of dictionaries, where only the id field is used
  for each entry.
- `projects` – List of projects which this group should have access
  to.

Example:

```
>>> client.update_group('1jo-WmmyRvC8UYtPMIQaoQ', 'Team West')
{
    u'id': u'1jo-WmmyRvC8UYtPMIQaoQ',
    u'name': 'Team West',
    u'members': [
        {
            u'email': u'user01@example.com',
            u'full_name': u'User 1',
            u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
            u'role': u'user',
            u'role_permissions': [u'user'],
            u'tenant': 'lW8-FnZlQYWBimxFknYitw'
        }
    ]
}
```

**`update_project_member(project_id, member_id, role)`**

Modifies a project membership.

Right now only the role can be changed, so that argument is required.

Parameters

- `project_id` – Project identifier of the project in which to
  modify the member.
- `member_id` – Identifier of the user or group to be updated.
- `role` – New role of the member. Allowed values: reader,
  member, admin.

Example:

```
>>> client.update_project_member('2sic33jZTi-ifflvQAVcfw',
...                              'H5Qv-WhgSBGW0WL8xolSCQ',
...                              'admin')
{
   u'email': u'user01@example.com',
   u'full_name': u'User 1',
   u'member_id': u'H5Qv-WhgSBGW0WL8xolSCQ',
   u'member_type': u'admin',
   …
}
```

**`update_user_data(user_id, changes, api_version='v1')`**

Update data for the given user. Any value can be set and will be
returned again when getting the user.

Parameters

- `user_id` – User identifier.
- `changes` – A dictionary containing user data to be updated.
- `api_version` – API version to use.

Returns

A dictionary which contains the updated user data.

Example:

```
>>> client.update_user_data('H5Qv-WhgSBGW0WL8xolSCQ',
...                         {'name': 'John Smith'})
{u'email': u'test@test.com',
 u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
 u'name': u'John Smith',
 u'tenant': u'test'}
```

**`update_workspace(workspace_domain, title)`**

Update a workspace.

Parameters

- `workspace_domain` – Domain of the workspace to update.
- `title` – New workspace title.

Example:

```
>>> client.update_workspace("workspace-5", title="Workspace Five")
{"domain": "workspace-5", "title": "Workspace Five"}
```