Aims ¶

Table of Contents

Aims
- Client

Client ¶

class Aims.Client¶

A client object representing ‘Aims’ Service:

import almdrlib

client = almdrlib.client('aims')

Available methods:

authenticate()
change_password()
create_access_key()
create_role()
create_user()
delete_access_key()
delete_role()
delete_user()
get_access_key()
get_account_details()
get_account_relationship()
get_account_relationship_topology()
get_accounts_details_by_name()
get_assigned_role_ids()
get_assigned_roles()
get_global_role_details()
get_role_details()
get_token_info()
get_user_details()
get_user_details_by_email()
get_user_details_by_id()
get_user_details_by_username()
get_user_permissions()
grant_user_role()
initiate_password_reset()
list_access_keys()
list_account_ids_by_relationship()
list_accounts_by_relationship()
list_global_roles()
list_roles()
list_users()
list_users_by_email()
mfa_enroll()
remove_mfa_device()
reset_password()
revoke_user_role()
update_access_key()
update_account_details()
update_role_details()
update_user_details()

authenticate(**kwargs)¶

Authenticate a user’s identity

The authenticate endpoint is used to verify a user’s credentials (access key or username/password). Users may authenticate by base64 encoding the string username:password (or access_key_id:secret_key) and prepending it with the string Basic per RFC 2617. Note that common tools like curl and most HTTP libraries support encoding this automatically.

Successful authentication returns 200 OK with a JSON body containing the key authentication.token. This token may be passed (as the X-Aims-Auth-Token header) to subsequent API requests which require a user to be authenticated. The user’s profile data is also included in the authentication key of the response body (see the examples below).

If authentication fails, 401 Unauthorized with an empty body and no HTTP headers is returned to the client.

Multi-Factor Authentication (MFA)

If the user is enrolled in Multi-Factor Authentication, then the mfa_code parameter must be passed. If a user inputs their correct username:password, but does not include the mfa_code, then a 401 Unauthorized with a JSON body containing the mfa_code_required error key is returned to the client. If the user is required to use MFA but has not configured it, the error key is mfa_enrollment_required instead. In both cases, an x-aims-session-token header is also returned. This session token can be used to complete authentication without re-entering the username and password, but must be used within 3 minutes.

If an mfa_code is required, the client can call POST /aims/v1/authenticate again with the required mfa_code in the JSON POST body and either:

The x-aims-session-token header from the initial authentication attempt
The Basic Authorization header with the username:password described above

Upon successful authentication, 200 OK is returned with a complete body as described above.

If the x-aims-session-token header is expired or invalid, 401 Unauthorized with a JSON body containing the invalid_session_token error key is returned to the client.

If the mfa_code value is incorrect or missing, 401 Unauthorized with an empty body and no HTTP headers is returned to the client.

Request Syntax

response = client.authenticate(
    mfa_code='string'
    x_aims_session_token='string'
)

Parameters

mfa_code (string) – The MFA code generated by the user’s MFA device
x_aims_session_token (string) – The session token for authenticating with mfa_code; The session token header from a call to POST /aims/v1/authenticate. Note that this header is optional.

Return type

dict

Returns

Response Syntax

{
    'authentication': {
        'account': {
            'accessible_locations': [
                'string'
            ],
            'active': 'False|True',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'default_location': 'string',
            'id': 'string',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'version': 'number'
        },
        'token': 'string',
        'token_expiration': 'number',
        'user': {
            'access_keys': [
                {
                    'access_key_id': 'string',
                    'created': {
                        'at': 'number',
                        'by': 'string'
                    },
                    'label': 'string',
                    'last_login': 'number',
                    'modified': {
                        'at': 'number',
                        'by': 'string'
                    }
                }
            ],
            'account_id': 'string',
            'active': 'False|True',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'email': 'string',
            'id': 'string',
            'linked_users': [
                {
                    'location': 'string',
                    'user_id': 'number'
                }
            ],
            'locked': 'False|True',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'user_credential': {
                'created': {
                    'at': 'number',
                    'by': 'string'
                },
                'last_login': 'number',
                'modified': {
                    'at': 'number',
                    'by': 'string'
                },
                'one_time_password': 'False|True',
                'version': 'number'
            },
            'username': 'string',
            'version': 'number'
        }
    }
}

Response Definitions

authentication (dict) –

account (dict) – [REQUIRED]

AIMS Account Information

accessible_locations (list) –

List of Account’s Accessible Locations

(string) –

active (boolean) –

Account Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

default_location (string) –

Account’s Default Location

id (string) –

Account ID

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Account Name

version (number) –

Object Version

token (string) –

token_expiration (number) –

user (dict) –

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

change_password(**kwargs)¶

The new password must conform to the following standards:

Cannot be identical to current or previous passwords (up to 4 previous passwords checked)
Length of at least 12 characters
Contain three of four possible character types:
- Upper case characters
- Lower case characters
- Numbers
- Special characters (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~)
Passwords can be specified as UTF-8. Characters in languages that do not have upper or lower case variants qualify as either upper or lower case.

Request Syntax

response = client.change_password(
    current_password='string'
    email='string'
    new_password='string'
)

Parameters

current_password (string) –
[REQUIRED]

Current password
email (string) –
[REQUIRED]

Email address
new_password (string) –
[REQUIRED]

New password

Returns: None

create_access_key(**kwargs)¶

Create an access key for a user

A label can be associated with an access key. If a label is specified, a valid JSON body must be provided. No more than 5 keys can be created for a user.

Request Syntax

response = client.create_access_key(
    account_id='string'
    label='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
label (string) – A label for the access key
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'access_key_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'label': 'string',
    'last_login': 'number',
    'modified': {
        'at': 'number',
        'by': 'string'
    }
}

Response Definitions

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

create_role(**kwargs)¶

Create a role

Request Syntax

response = client.create_role(
    account_id='string'
    name='string'
    permissions={}
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
name (string) –
[REQUIRED]

Role name
permissions (dict) –
[REQUIRED]

Role permissions

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'legacy_permissions': [
        'string'
    ],
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'permissions': {
        '[permission]': 'string'
    },
    'version': 'number'
}

Response Definitions

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

create_user(**kwargs)¶

Create a user

The user’s password must conform to the following standards:

Length of at least 12 characters
Contain three of four possible character types:
- Upper case characters
- Lower case characters
- Numbers
- Special characters (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~)

Passwords can be specified as UTF-8. Characters in languages that do not have upper or lower case variants qualify as either upper or lower case.

It is possible to set a one time password by sending a query parameter (one_time_password) with a boolean value, see example below.

The mobile phone number, phone number and webhook url fields are optional. If mobile phone and/or phone included, their strings must contain at least 10 numbers and be no more than 30 characters. If webhook url is included, the url must be a valid http/https url.

The notifications_only flag is optional. If the flag is set to true, the user will not receive welcome email, password expiration/change related emails, and the user will not be able to authenticate.

Request Syntax

response = client.create_user(
    account_id='string'
    active='False|True'
    email='string'
    mobile_phone='string'
    name='string'
    notifications_only='False|True'
    one_time_password='False|True'
    password='string'
    phone='string'
    role_id='string'
    webhook_url='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
active (boolean) –
User status.

Default: True
email (string) –
[REQUIRED]

Email address
mobile_phone (string) – An optional string containing a user’s mobile phone number.
name (string) –
[REQUIRED]

Username
notifications_only (boolean) –
An optional boolean flag to make the user notifications only.

Default: False
one_time_password (boolean) – Create or update a user with a one time password credential. If not set, one_time_password defaults to false.
password (string) – Password If a password is not passed to the user create call, the user will receive an email with a link to set the password.
phone (string) – An optional string containing a user’s phone number.
role_id (string) – Role Id to grant the newly created user. The user will be granted this role unless it is the first user created in the account, which is always granted the administrator role.
webhook_url (string) – An optional string containing a user’s webhook url.

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

delete_access_key(**kwargs)¶

Delete a user’s access key

Request Syntax

response = client.delete_access_key(
    access_key_id='string'
    account_id='string'
    user_id='string'
)

Parameters

access_key_id (string) –
[REQUIRED]

Access Key ID.
account_id (string) –
[REQUIRED]

AIMS Account ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Returns: None

delete_role(**kwargs)¶

Role deletion is permanent. Due to caching and the distributed nature of the data store, role deletion is also asynchronous; as a result, clients may be able to retrieve the deleted role (and grants of it to users) for a brief period after deleting it.

Request Syntax

response = client.delete_role(
    account_id='string'
    role_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
role_id (string) –
[REQUIRED]

Role ID.

Returns: None

delete_user(**kwargs)¶

Delete a user User deletion is permanent. Due to caching and the distributed nature of the data store, user deletion is also asynchronous; as a result, clients may be able to retrieve the deleted user for a brief period after deleting it.

Users cannot delete themselves. Users that have been assigned the Administrator role can only be deleted if there is at least one other user with the Administrator role present.

Request Syntax

response = client.delete_user(
    account_id='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Returns: None

get_access_key(**kwargs)¶

Get access key by ID

Request Syntax

response = client.get_access_key(
    access_key_id='string'
    account_id='string'
    user_id='string'
)

Parameters

access_key_id (string) –
[REQUIRED]

Access Key ID.
account_id (string) –
[REQUIRED]

AIMS Account ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'access_key_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'label': 'string',
    'last_login': 'number',
    'modified': {
        'at': 'number',
        'by': 'string'
    }
}

Response Definitions

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

get_account_details(**kwargs)¶

Get account details

Request Syntax

response = client.get_account_details(
    account_id='string'
)

Parameters

account_id (string) –

[REQUIRED]

AIMS Account ID.

Return type

dict

Returns

Response Syntax

{
    'accessible_locations': [
        'string'
    ],
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'default_location': 'string',
    'id': 'string',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'version': 'number'
}

Response Definitions

accessible_locations (list) –

List of Account’s Accessible Locations

(string) –

active (boolean) –

Account Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

default_location (string) –

Account’s Default Location

id (string) –

Account ID

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Account Name

version (number) –

Object Version

get_account_relationship(**kwargs)¶

Check if the specified relationship between two accounts exists. Responds with 204 No Content if the specified relationship exists between the two accounts. Responds with 404 Not Found if the relationship between the two accounts does not exist.

Note that both the given account_id and related_account_id must be visible to the client. If either is not, a 403 Forbidden is returned to the client.

Request Syntax

response = client.get_account_relationship(
    account_id='string'
    related_account_id='string'
    relationship='bills_to'|'managed'|'managing'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
related_account_id (string) –
[REQUIRED]

Possibly related account ID
relationship (string) –
[REQUIRED]

Account relationship. Accepted values: bills_to, managed, managing.

Valid values: bills_to, managed, managing

Returns: None

get_account_relationship_topology(**kwargs)¶

This endpoint render’s an accounts related accounts topologically by adding a :relationship field to the account object, which contains an array of accounts that are directly related to it. In turn, each of those accounts is decorated with a :relationship field that contains the (similarly decorated) accounts directly related to it. This continues recursively till a “leaf” account (an account with no direct relationships) is decorated with {"<relationship>": []}. Clients may use this endpoint to understand how an accounts related accounts are related to each other, e.g., understanding “direct descendants,” “direct ancestors,” “grand ancestors,” etc.

Note that the managing account relationship is the inverse of the managed relationship. That is, looking up the managing relationship returns the list of accounts that have a managed relationship to the given account_id. This list shows only accounts which the calling client is authorized to view, so, for example, looking up managing accounts for the client’s own account will result in an empty topology regardless of whether accounts not visible to the client have a managed relationship to the given account_id.

Request Syntax

response = client.get_account_relationship_topology(
    accessible_locations='string'
    account_id='string'
    active='False|True'
    fields='string'
    relationship='managed'|'managing'
)

Parameters

accessible_locations (string) – Filter by accessible_location ids. Use comma separated format for multiple locations e.g. “insight-us-virginia,defender-us-denver”
account_id (string) –
[REQUIRED]

AIMS Account ID.
active (boolean) – Filter by account active status
fields (string) –
[REQUIRED]

A comma-separated list of fields to include in the account, or simply all to include all fields. Only top-level fields are supported. Note that the "id" is always included: If it is not included in the fields option, it will be automatically added to the fields given, if any.
relationship (string) –
[REQUIRED]

Account relationship. Note that this does not support bills_to relationship yet.

Valid values: managed, managing

Return type

dict

Returns

Response Syntax

{
    'topology': {}
}

Response Definitions

topology (dict) –

get_accounts_details_by_name(**kwargs)¶

Returns a list of accounts having the given name that the client has permission to access.

Note that if an empty list is returned, it may mean that an account with the name exists, but the client does not have permission to access it.

Request Syntax

response = client.get_accounts_details_by_name(
    name='string'
)

Parameters

name (string) –

[REQUIRED]

Account name, URL encoded according to RFC3986. Note that the + character is not interpreted as a space (`) in this scheme; use%20` for spaces instead.

Return type

dict

Returns

Response Syntax

{
    'accounts': [
        {
            'accessible_locations': [
                'string'
            ],
            'active': 'False|True',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'default_location': 'string',
            'id': 'string',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'version': 'number'
        }
    ]
}

Response Definitions

accounts (list) –

(dict) –

AIMS Account Information

accessible_locations (list) –

List of Account’s Accessible Locations

(string) –

active (boolean) –

Account Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

default_location (string) –

Account’s Default Location

id (string) –

Account ID

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Account Name

version (number) –

Object Version

get_assigned_role_ids(**kwargs)¶

Get user role ids

Request Syntax

response = client.get_assigned_role_ids(
    account_id='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'role_ids': 'string'
}

Response Definitions

role_ids (string) –

get_assigned_roles(**kwargs)¶

Get user roles

Request Syntax

response = client.get_assigned_roles(
    account_id='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'roles': [
        {
            'account_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'id': 'string',
            'legacy_permissions': [
                'string'
            ],
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'permissions': {
                '[permission]': 'string'
            },
            'version': 'number'
        }
    ]
}

Response Definitions

roles (list) –

(dict) –

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

get_global_role_details(**kwargs)¶

Get global role, a role that is shared among accounts.

Request Syntax

response = client.get_global_role_details(
    role_id='string'
)

Parameters

role_id (string) –

[REQUIRED]

Role ID.

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'legacy_permissions': [
        'string'
    ],
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'permissions': {
        '[permission]': 'string'
    },
    'version': 'number'
}

Response Definitions

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

get_role_details(**kwargs)¶

Get role.

Request Syntax

response = client.get_role_details(
    account_id='string'
    role_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
role_id (string) –
[REQUIRED]

Role ID.

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'legacy_permissions': [
        'string'
    ],
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'permissions': {
        '[permission]': 'string'
    },
    'version': 'number'
}

Response Definitions

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

get_token_info(**kwargs)¶

Obtain Authentication Token Information (Account, User, Roles, etc.)

Request Syntax

response = client.get_token_info(
)

Return type

dict

Returns

Response Syntax

{
    'account': {
        'accessible_locations': [
            'string'
        ],
        'active': 'False|True',
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'default_location': 'string',
        'id': 'string',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'name': 'string',
        'version': 'number'
    },
    'entity_id': 'string',
    'entity_type': 'string',
    'requester_id': 'string',
    'roles': [
        {
            'account_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'id': 'string',
            'legacy_permissions': [
                'string'
            ],
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'permissions': {
                '[permission]': 'string'
            },
            'version': 'number'
        }
    ],
    'token_expiration': 'number',
    'user': {
        'access_keys': [
            {
                'access_key_id': 'string',
                'created': {
                    'at': 'number',
                    'by': 'string'
                },
                'label': 'string',
                'last_login': 'number',
                'modified': {
                    'at': 'number',
                    'by': 'string'
                }
            }
        ],
        'account_id': 'string',
        'active': 'False|True',
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'email': 'string',
        'id': 'string',
        'linked_users': [
            {
                'location': 'string',
                'user_id': 'number'
            }
        ],
        'locked': 'False|True',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'name': 'string',
        'user_credential': {
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'one_time_password': 'False|True',
            'version': 'number'
        },
        'username': 'string',
        'version': 'number'
    }
}

Response Definitions

account (dict) – [REQUIRED]

AIMS Account Information

accessible_locations (list) –

List of Account’s Accessible Locations

(string) –

active (boolean) –

Account Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

default_location (string) –

Account’s Default Location

id (string) –

Account ID

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Account Name

version (number) –

Object Version

entity_id (string) –

entity_type (string) –

requester_id (string) –

roles (list) –

(dict) –

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

token_expiration (number) –

user (dict) –

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

get_user_details(**kwargs)¶

Get user details

Request Syntax

response = client.get_user_details(
    account_id='string'
    include_access_keys='False|True'
    include_role_ids='False|True'
    include_user_credential='False|True'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
include_access_keys (boolean) – Optional query parameter to include the access keys of the user. If not set, defaults to true.
include_role_ids (boolean) – Optional query parameter to return the list of role ids assigned to the user. If not set, defaults to true.
include_user_credential (boolean) – Optional query parameter to include the user credential object of the user. If not set, defaults to true.
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

get_user_details_by_email(**kwargs)¶

Get user details by email

This endpoint has been deprecated and only mantained for backwards compatibility. This operates the same way of get user details by username. In order to retrieve users by email, see list users by email.

Request Syntax

response = client.get_user_details_by_email(
    email='string'
    include_access_keys='False|True'
    include_role_ids='False|True'
    include_user_credential='False|True'
)

Parameters

email (string) –
[REQUIRED]

User Email (URL encoded)
include_access_keys (boolean) – Optional query parameter to include the access keys of the user. If not set, defaults to true.
include_role_ids (boolean) – Optional query parameter to return the list of role ids assigned to the user. If not set, defaults to true.
include_user_credential (boolean) – Optional query parameter to include the user credential object of the user. If not set, defaults to true.

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

get_user_details_by_id(**kwargs)¶

Get user details by user ID

Request Syntax

response = client.get_user_details_by_id(
    include_access_keys='False|True'
    include_role_ids='False|True'
    include_user_credential='False|True'
    user_id='string'
)

Parameters

include_access_keys (boolean) – Optional query parameter to include the access keys of the user. If not set, defaults to true.
include_role_ids (boolean) – Optional query parameter to return the list of role ids assigned to the user. If not set, defaults to true.
include_user_credential (boolean) – Optional query parameter to include the user credential object of the user. If not set, defaults to true.
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

get_user_details_by_username(**kwargs)¶

Get user details by username

Request Syntax

response = client.get_user_details_by_username(
    include_access_keys='False|True'
    include_role_ids='False|True'
    include_user_credential='False|True'
    username='string'
)

Parameters

include_access_keys (boolean) – Optional query parameter to include the access keys of the user. If not set, defaults to true.
include_role_ids (boolean) – Optional query parameter to return the list of role ids assigned to the user. If not set, defaults to true.
include_user_credential (boolean) – Optional query parameter to include the user credential object of the user. If not set, defaults to true.
username (string) –
[REQUIRED]

User Username (URL encoded).

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

get_user_permissions(**kwargs)¶

Get user permissions

User’s permissions are derived from the intersection of the permissions that they have based on the roles granted to the user.

For instance, If a user has a role that allows them permission {"\*:own:get:account": "allowed"}, and another role that denies them that same permission {"\*:own:get:account": "denied"}, the permissions list will only show the deny entry.

Request Syntax

response = client.get_user_permissions(
    account_id='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'permissions': [
        {}
    ]
}

Response Definitions

permissions (list) –

(dict) –

grant_user_role(**kwargs)¶

Grant a role to a user

Users cannot grant roles to themselves. When granting the Administrator role to a user, all roles previously granted to that user will be revoked.

Request Syntax

response = client.grant_user_role(
    account_id='string'
    role_id='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
role_id (string) –
[REQUIRED]

Role ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Returns: None

initiate_password_reset(**kwargs)¶

Initiate the password reset process for a user

Request Syntax

response = client.initiate_password_reset(
    email='string'
    return_to='string'
)

Parameters

email (string) –
[REQUIRED]

Email address
return_to (string) –
[REQUIRED]

A URL to return to after successfully resetting the user’s password

Returns: None

list_access_keys(**kwargs)¶

List user access keys.

If an output format is not specified using the out query parameter, only access key IDs are returned.

Request Syntax

response = client.list_access_keys(
    account_id='string'
    out='ids_only'|'full'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
out (string) –
Query param to define if the output should return a full (full) description of access keys or the list of access keys ids only (ids_only). If not set, defaults to ids_only

Valid values: ids_only, full
user_id (string) –
[REQUIRED]

AIMS User ID

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        'dict|string'
    ]
}

Response Definitions

access_keys (list) –

(dict) –

list_account_ids_by_relationship(**kwargs)¶

Note that the managing account relationship is the inverse of the managed relationship. That is, looking up account IDs by the managing relationship denotes the list of account IDs that have a managed relationship to the given account_id. This list shows only account IDs which the calling client is authorized to view, so, for example, looking up managing account IDs for the client’s own account will return an empty list regardless of whether accounts not visible to the client have a managed relationship to the given account_id.

Request Syntax

response = client.list_account_ids_by_relationship(
    accessible_locations='string'
    account_id='string'
    active='False|True'
    mfa_required='string'
    relationship='bills_to'|'managed'|'managing'
)

Parameters

accessible_locations (string) – Filter by accessible_location ids. Use comma separated format for multiple locations e.g. “insight-us-virginia,defender-us-denver”
account_id (string) –
[REQUIRED]

AIMS Account ID.
active (boolean) – Filter by account active status
mfa_required (string) – Filter by account mfa_required property
relationship (string) –
[REQUIRED]

Account relationship. Accepted values: bills_to, managed, managing.

Valid values: bills_to, managed, managing

Return type

dict

Returns

Response Syntax

{
    'account_ids': [
        'string'
    ]
}

Response Definitions

account_ids (list) –

(string) –

list_accounts_by_relationship(**kwargs)¶

Note that the managing account relationship is the inverse of the managed relationship. That is, looking up the managing relationship returns the list of accounts that have a managed relationship to the given account_id. This list shows only accounts which the calling client is authorized to view, so, for example, looking up managing accounts for the client’s own account will return an empty list regardless of whether accounts not visible to the client have a managed relationship to the given account_id.

Request Syntax

response = client.list_accounts_by_relationship(
    accessible_locations='string'
    account_id='string'
    active='False|True'
    mfa_required='string'
    relationship='bills_to'|'managed'|'managing'
)

Parameters

accessible_locations (string) – Filter by accessible_location ids. Use comma separated format for multiple locations e.g. “insight-us-virginia,defender-us-denver”
account_id (string) –
[REQUIRED]

AIMS Account ID.
active (boolean) – Filter by account active status
mfa_required (string) – Filter by account mfa_required property
relationship (string) –
[REQUIRED]

Account relationship. Accepted values: bills_to, managed, managing.

Valid values: bills_to, managed, managing

Return type

dict

Returns

Response Syntax

{
    'accounts': [
        {
            'accessible_locations': [
                'string'
            ],
            'active': 'False|True',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'default_location': 'string',
            'id': 'string',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'version': 'number'
        }
    ]
}

Response Definitions

accounts (list) –

(dict) –

AIMS Account Information

accessible_locations (list) –

List of Account’s Accessible Locations

(string) –

active (boolean) –

Account Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

default_location (string) –

Account’s Default Location

id (string) –

Account ID

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Account Name

version (number) –

Object Version

list_global_roles(**kwargs)¶

List global roles, roles that are shared among all accounts.

Request Syntax

response = client.list_global_roles(
)

Return type

dict

Returns

Response Syntax

{
    'roles': [
        {
            'account_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'id': 'string',
            'legacy_permissions': [
                'string'
            ],
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'permissions': {
                '[permission]': 'string'
            },
            'version': 'number'
        }
    ]
}

Response Definitions

roles (list) –

(dict) –

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

list_roles(**kwargs)¶

List roles for an account. Global roles are included in the list.

Request Syntax

response = client.list_roles(
    account_id='string'
)

Parameters

account_id (string) –

[REQUIRED]

AIMS Account ID.

Return type

dict

Returns

Response Syntax

{
    'roles': [
        {
            'account_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'id': 'string',
            'legacy_permissions': [
                'string'
            ],
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'permissions': {
                '[permission]': 'string'
            },
            'version': 'number'
        }
    ]
}

Response Definitions

roles (list) –

(dict) –

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

list_users(**kwargs)¶

List account users

Request Syntax

response = client.list_users(
    account_id='string'
    include_access_keys='False|True'
    include_role_ids='False|True'
    include_user_credential='False|True'
    role_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
include_access_keys (boolean) – Optional query parameter to include the access keys of each user in the response. If not set, defaults to false.
include_role_ids (boolean) – Optional query parameter to include the list of role ids assigned to each user in the response. If not set, defaults to false.
include_user_credential (boolean) – Optional query parameter to include the user credential object of each user in the response. If not set, defaults to false.
role_id (string) – The role ID assigned to the user. If passed, only users who are granted the role with the specified role ID are returned.

Return type

dict

Returns

Response Syntax

{
    'users': [
        {
            'access_keys': [
                {
                    'access_key_id': 'string',
                    'created': {
                        'at': 'number',
                        'by': 'string'
                    },
                    'label': 'string',
                    'last_login': 'number',
                    'modified': {
                        'at': 'number',
                        'by': 'string'
                    }
                }
            ],
            'account_id': 'string',
            'active': 'False|True',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'email': 'string',
            'id': 'string',
            'linked_users': [
                {
                    'location': 'string',
                    'user_id': 'number'
                }
            ],
            'locked': 'False|True',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'user_credential': {
                'created': {
                    'at': 'number',
                    'by': 'string'
                },
                'last_login': 'number',
                'modified': {
                    'at': 'number',
                    'by': 'string'
                },
                'one_time_password': 'False|True',
                'version': 'number'
            },
            'username': 'string',
            'version': 'number'
        }
    ]
}

Response Definitions

users (list) –

(dict) –

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

list_users_by_email(**kwargs)¶

List Users By Email

Request Syntax

response = client.list_users_by_email(
    email='string'
    include_access_keys='False|True'
    include_role_ids='False|True'
    include_user_credential='False|True'
)

Parameters

email (string) –
[REQUIRED]

User Email (URL encoded)
include_access_keys (boolean) – Optional query parameter to include the access keys of each user in the response. If not set, defaults to false.
include_role_ids (boolean) – Optional query parameter to include the list of role ids assigned to each user in the response. If not set, defaults to false.
include_user_credential (boolean) – Optional query parameter to include the user credential object of each user in the response. If not set, defaults to false.

Return type

dict

Returns

Response Syntax

{
    'users': [
        {
            'access_keys': [
                {
                    'access_key_id': 'string',
                    'created': {
                        'at': 'number',
                        'by': 'string'
                    },
                    'label': 'string',
                    'last_login': 'number',
                    'modified': {
                        'at': 'number',
                        'by': 'string'
                    }
                }
            ],
            'account_id': 'string',
            'active': 'False|True',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'email': 'string',
            'id': 'string',
            'linked_users': [
                {
                    'location': 'string',
                    'user_id': 'number'
                }
            ],
            'locked': 'False|True',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'user_credential': {
                'created': {
                    'at': 'number',
                    'by': 'string'
                },
                'last_login': 'number',
                'modified': {
                    'at': 'number',
                    'by': 'string'
                },
                'one_time_password': 'False|True',
                'version': 'number'
            },
            'username': 'string',
            'version': 'number'
        }
    ]
}

Response Definitions

users (list) –

(dict) –

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

mfa_enroll(**kwargs)¶

Enroll a user in multi-factor authentication. Requires either username/password or a valid x-aims-session-token header to enroll. The user must input an RFC 6238 compatible Time-based One-Time Password secret as an otpauth:// format URI (See Google Authenticator’s Key URI Format Docs for complete details). The following parameters must be set in the mfa_uri:

TYPE must be totp
LABEL must be the issuer “Alert Logic”, colon “:” and user’s email, e.g. Alert%20Logic:admin@company.com
secret must be an arbitrary value between 16-20 bytes, in non-padded Base32 encoding, e.g., the ASCII string "1s tHiS s3kr3t S4F3?" is GFZSA5CINFJSA4ZTNNZDG5BAKM2EMMZ7 in Base32
issuer must be “Alert Logic”, i.e. issuer=Alert%20Logic
algorithm must be SHA1
digits must be an integer greater than or equal to 6; the default (if missing) is 6
period must be an integer between 30-60 (seconds); the default (if missing) is 30

Example mfa_uri: otpauth://totp/Alert%20Logic:admin@company.com?secret=GFZSA5CINFJSA4ZTNNZDG5BAKM2EMMZ7&issuer=Alert%20Logic&algorithm=SHA1

The request must also include mfa_codes, an array of 2 or more MFA codes generated by the MFA device. These codes must be valid prior to successful device enrollment.

A user can only enroll an MFA device if they have not already enrolled one. If the user has already enrolled an MFA device, that device must be removed prior to enrolling a different one.

Once a user enrolls an MFA device, the user is required to provide a valid mfa_code during username/password authentication.

Request Syntax

response = client.mfa_enroll(
    email='string'
    mfa_codes=[
        'string'
    ]
    mfa_uri='string'
    password='string'
    x_aims_session_token='string'
)

Parameters

email (string) – User email address (username)
mfa_codes (list) –
[REQUIRED]

list of String 2 or more MFA codes generated by the MFA device for verification.
- (string) –
mfa_uri (string) –
[REQUIRED]

TOTP MFA URI, in otpauth:// format
password (string) – User password
x_aims_session_token (string) – The session token for authenticating with mfa_code; The session token header from a call to POST /aims/v1/authenticate. Note that this header is optional.

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

remove_mfa_device(**kwargs)¶

Remove a user’s MFA device

Removes a user’s MFA device. This endpoint can be called by any authenticated user to remove their own MFA device. Administrators (or other users with sufficient permissions) may remove the MFA device of another user.

Once a user’s MFA device is removed (user field mfa_enabled set to false), the user will no longer be required to enter an mfa_code during authentication. The user may then enroll a new MFA device if desired.

Request Syntax

response = client.remove_mfa_device(
    username='string'
)

Parameters

username (string) –

[REQUIRED]

User Username (URL encoded).

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

reset_password(**kwargs)¶

Reset a user’s password using a token

The token is emailed to a user’s email when POST /aims/v1/reset_password is called successfully.

The new password must conform to the following standards:

Cannot be identical to current or previous passwords (up to 4 previous passwords checked)
Length of at least 12 characters
Contain three of four possible character types:
- Upper case characters
- Lower case characters
- Numbers
- Special characters (!”#$%&’()*+,-./:;<=>?@[]^_`{|}~)

Passwords can be specified as UTF-8. Characters in languages that do not have upper or lower case variants qualify as either upper or lower case.

Request Syntax

response = client.reset_password(
    password='string'
    token='string'
)

Parameters

password (string) –
[REQUIRED]

New password
token (string) –
[REQUIRED]

Password reset token

Returns: None

revoke_user_role(**kwargs)¶

Revoke a role for a user

Users cannot revoke roles assigned to themselves. When revoking the Administrator role from a user, there must be at least one other user with the Administrator role present.

Request Syntax

response = client.revoke_user_role(
    account_id='string'
    role_id='string'
    user_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
role_id (string) –
[REQUIRED]

Role ID.
user_id (string) –
[REQUIRED]

AIMS User ID

Returns: None

update_access_key(**kwargs)¶

Update access key by ID

Request Syntax

response = client.update_access_key(
    access_key_id='string'
    label='string'
)

Parameters

access_key_id (string) –
[REQUIRED]

Access Key ID.
label (string) – access key label to be updated

Return type

dict

Returns

Response Syntax

{
    'access_key_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'label': 'string',
    'last_login': 'number',
    'modified': {
        'at': 'number',
        'by': 'string'
    }
}

Response Definitions

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

update_account_details(**kwargs)¶

To update an account, the client must have permission to update the specified account (aims:<account_id>:update:account). The mfa_required field may be updated by any client with this permission.

Request Syntax

response = client.update_account_details(
    account_id='string'
    mfa_required='False|True'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
mfa_required (boolean) – Determines whether multi-factor authentication (MFA) is required for users of the account. Defaults to false.

Return type

dict

Returns

Response Syntax

{
    'accessible_locations': [
        'string'
    ],
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'default_location': 'string',
    'id': 'string',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'version': 'number'
}

Response Definitions

accessible_locations (list) –

List of Account’s Accessible Locations

(string) –

active (boolean) –

Account Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

default_location (string) –

Account’s Default Location

id (string) –

Account ID

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Account Name

version (number) –

Object Version

update_role_details(**kwargs)¶

The role’s name, permissions, or both may be updated.

Request Syntax

response = client.update_role_details(
    account_id='string'
    name='string'
    permissions={}
    role_id='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
name (string) – Role Name
permissions (dict) – Role Permissions
role_id (string) –
[REQUIRED]

Role ID.

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'legacy_permissions': [
        'string'
    ],
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'permissions': {
        '[permission]': 'string'
    },
    'version': 'number'
}

Response Definitions

account_id (string) –

Account ID

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

id (string) –

Role ID

legacy_permissions (list) –

(string) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

Role Name

permissions (dict) –

[permission] (string) –

version (number) –

Object Version

update_user_details(**kwargs)¶

Update user details

The user’s active status, name, password, email, mobile phone, notifications only, or any combination of the five may be updated. Note that, if the client is requesting a change to his/her own user, the password, active and notifications_only fields may not be updated. Fields included in the request body that are not allowed to be updated are ignored. In order for the user to change his own password, use Change Password or Reset Password endpoints instead. Request a system admin user to update user’s active field.

The user’s password must conform to the following standards:

Cannot be identical to current or previous passwords (up to 4 previous passwords checked)
Length of at least 12 characters
Contain three of four possible character types:
- Upper case characters
- Lower case characters
- Numbers
- Special characters (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~)

Passwords can be specified as UTF-8. Characters in languages that do not have upper or lower case variants qualify as either upper or lower case.

It is possible to set a one time password by sending a query parameter ("one_time_password") with a boolean value, see example below.

The mobile phone number, phone number and webhook url fields are optional. If mobile phone and/or phone included, their strings must contain at least 10 numbers and be no more than 30 characters. If webhook url is included, the url must be a valid http/https url. In order to clear the optional fields, mobile phone, phone and webhook url, you must set it to an empty string as seen in “clear optional field” usage example.

The notifications only flag field is optional. If the flag is set to true, the user will not receive password expiration/change related emails and the user will not be able to authenticate.

Request Syntax

response = client.update_user_details(
    account_id='string'
    active='False|True'
    email='string'
    mobile_phone='string'
    name='string'
    notifications_only='False|True'
    one_time_password='False|True'
    password='string'
    phone='string'
    user_id='string'
    webhook_url='string'
)

Parameters

account_id (string) –
[REQUIRED]

AIMS Account ID.
active (boolean) – User status
email (string) – New email address
mobile_phone (string) – An optional string containing a user’s mobile phone number.
name (string) – New user name
notifications_only (boolean) – An optional boolean flag to make the user notifications only.
one_time_password (boolean) – Create or update a user with a one time password credential. If not set, one_time_password defaults to false.
password (string) – New password
phone (string) – An optional string containing a user’s phone number.
user_id (string) –
[REQUIRED]

AIMS User ID
webhook_url (string) – An optional string containing a user’s webhook url.

Return type

dict

Returns

Response Syntax

{
    'access_keys': [
        {
            'access_key_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'label': 'string',
            'last_login': 'number',
            'modified': {
                'at': 'number',
                'by': 'string'
            }
        }
    ],
    'account_id': 'string',
    'active': 'False|True',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'email': 'string',
    'id': 'string',
    'linked_users': [
        {
            'location': 'string',
            'user_id': 'number'
        }
    ],
    'locked': 'False|True',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'name': 'string',
    'user_credential': {
        'created': {
            'at': 'number',
            'by': 'string'
        },
        'last_login': 'number',
        'modified': {
            'at': 'number',
            'by': 'string'
        },
        'one_time_password': 'False|True',
        'version': 'number'
    },
    'username': 'string',
    'version': 'number'
}

Response Definitions

access_keys (list) –

(dict) –

User Access Key

access_key_id (string) –

Access Key Id

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

label (string) –

Access Key Label

last_login (number) –

Last Login Epoch Timestamp

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

account_id (string) –

Account ID

active (boolean) –

User’s Active Status

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

email (string) –

User’s Email

id (string) –

UUID

linked_users (list) –

(dict) –

location (string) –

Linked User’s Location

user_id (number) –

Linked User’s ID

locked (boolean) –

User’s Locked Status

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

name (string) –

User’s Name

user_credential (dict) –

created (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID that Created the Object

last_login (number) –

modified (dict) –

at (number) –

Epoch & Unix Timestamp (RFC 3339)

by (string) –

User ID of the Last User that Modified the Object

one_time_password (boolean) –

version (number) –

Object Version

username (string) –

User’s Username

version (number) –

Object Version

Aims¶

Client¶

Aims ¶

Client ¶