UserApiMixin

UserApiMixin#

class UserApiMixin#

Bases: 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 Summary

add_group_member(group_id, user_id)

Adds a user to the group.

add_project_member(project_id, role[, ...])

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

add_user([email, password, role])

Add a new user to the current tenant.

add_workspace_users(workspace_domain, ...)

Adds users to a workspace by email address.

change_user_password(user_id, ...)

Change a user's password.

create_group(name[, members])

Create a new group.

create_workspace(title)

Create a new workspace.

delete_authentication(user_id, service)

Delete an authentication.

delete_grant(user_id, grant_id)

Delete a grant.

delete_group(group_id)

Delete a group.

delete_group_member(group_id, user_id)

Removes a user from the group.

delete_project_member(project_id, member_id)

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

delete_session(user_id, session_id)

Delete a session.

delete_user(user_id)

Delete a user from the system.

delete_workspace(workspace_domain)

Delete a workspace.

delete_workspace_user(workspace_domain, user_id)

Delete a user from the workspace.

get_authentication(user_id, service)

Retrieves an authentication for a given service.

get_group(group_id[, include_projects])

Returns details, including the members, of a group.

get_groups()

Returns all groups within the logged-in users tenant.

get_project_members(project_id)

Returns all users and groups associated with the given project.

get_session(user_id, session_id)

Get data of a specific session.

get_token_from_msexchuid(msexchuid)

Retrieves the OAUTH2 authentication token for a given user based

get_token_from_msexchuid_token(msexchuid_token)

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

get_user_data(user_id[, include_projects, ...])

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

get_user_grants(user_id)

Get all grants for the provided user.

get_users([include_config])

Returns all users within the logged-in users tenant.

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.

get_workspaces([include_projects, admin_only])

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

new_grant(user_id, type[, for_client_id, ...])

Create a new grant.

new_or_modify_authentication(user_id, ...[, ...])

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

set_workspace_user_role(workspace_domain, ...)

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

signup(email, password[, full_name])

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

update_group(group_id, name[, members, projects])

Modify a group's attributes.

update_project_member(project_id, member_id, ...)

Modifies a project membership.

update_user_data(user_id, changes[, api_version])

Update data for the given user.

Methods 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'[email protected]',
    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'[email protected]',
   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'fingerprints.*',
                    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", ["[email protected]", "[email protected]"], "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': '[email protected]',
          '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'[email protected]',
            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'[email protected]',
          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'[email protected]',
   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'fingerprints.read.*',
                    u'fingerprints.write.create.adhoc',
                    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'[email protected]',
 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'[email protected]',
        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": "[email protected]",
     "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.

Returns:

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

Example:

>>> client.new_grant('H5Qv-WhgSBGW0WL8xolSCQ', 'service',
...                  'abdc0183029498f20c38')
{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'}
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='[email protected]', 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'[email protected]',
            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'[email protected]',
   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'[email protected]',
 u'id': u'H5Qv-WhgSBGW0WL8xolSCQ',
 u'name': u'John Smith',
 u'tenant': u'test'}
Contents