Users

Users can perform a variety of actions in ThreatConnect depending on their user account type and their System and Organization role. In addition, users can be assigned to Workflow Cases, Workflow Tasks, and Task Groups.

Endpoint: /api/v3/security/users

Attention

Only API users with an Organization role of Organization Administrator can create, update, and delete users. API users with any other Organization role can only retrieve users.

Available Fields

You can retrieve a list of fields for the v3/security/users endpoint using the following query:

OPTIONS /v3/security/users?show=readonly

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request for the users object:

Field	Description	Type	Required for Creation?	Updatable?
disabled	Determines whether the user’s account is disabled	Boolean	FALSE	TRUE
firstName	The user’s first name	String	TRUE	TRUE
lastName	The user’s last name	String	TRUE	TRUE
locked	Determines whether the user’s account is locked	Boolean	FALSE	TRUE
logoutIntervalMinutes	The amount of time, in minutes, after which the user will be logged out of ThreatConnect	Integer	FALSE	TRUE
owner	The Organization to which the user belongs	String	TRUE	FALSE
ownerRoles	The user’s role within each Organization, Community, or Source to which they have access	String	TRUE	FALSE
password	The password for the user’s account	String	TRUE	TRUE
passwordResetRequired	Determines whether the user needs to reset their password the next time they log into ThreatConnect	Boolean	FALSE	TRUE
pseudonym	The user’s pseudonym	String	FALSE	TRUE
systemRole	The user’s System role (all System roles except API User may be used)	String	FALSE	TRUE
termsAccepted	Determines whether to present the user with ThreatConnect’s terms of service the next time they log into ThreatConnect	Boolean	FALSE	TRUE
twoFactorResetRequired	Determines whether to require the user to configure multi-factor authentication (MFA) for their account (or to reset MFA if the user already has it configured)	Boolean	FALSE	TRUE
uiTheme	Specifies whether to set the ThreatConnect user interface to a light or dark theme for the user (accepted values include “Light” and “Dark”)	String	FALSE	TRUE
userName	The username for the user’s account	String	TRUE	TRUE

Create Users

Attention

Only API users with an Organization role of Organization Administrator can create users.

The basic format for creating a user is:

POST /v3/security/users
{
    "firstName": "John",
    "lastName": "Smith",
    "userName": "[email protected]",
    "password": "Password1!",
    "owner": "Demo Organization",
    "ownerRoles": {
        "Demo Organization": "Organization Administrator"
    },
    "systemRole": "User"
}

For example, the following query will create a user account where the user will be required to reset their password and enroll in MFA after logging into ThreatConnect for the first time:

POST /v3/security/users
{
    "firstName": "Herschel",
    "lastName": "Hodges",
    "userName": "[email protected]",
    "password": "Password1!",
    "owner": "Demo Organization",
    "ownerRoles": {
        "Demo Organization": "Organization Administrator"
    },
    "systemRole": "User",
    "passwordResetRequired": true,
    "twoFactorResetRequired": true
}

JSON Response

{
    "data": {
        "id": 12,
        "userName": "[email protected]",
        "firstName": "Herschel",
        "lastName": "Hodges",
        "owner": "Demo Organization",
        "lastPasswordChange": "2022-09-07T12:11:13Z",
        "uiTheme": "Light",
        "termsAccepted": false,
        "logoutIntervalMinutes": 0,
        "systemRole": "User",
        "disabled": false,
        "locked": false,
        "passwordResetRequired": true,
        "twoFactorResetRequired": true
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a POST request for the users object.

Note

Creating users in bulk is not supported at this time.

Retrieve Users

When retrieving users, additional fields will be included in the response for API users with an Organization role of Organization Administrator. In the examples used in the following subsections, the response an API user with an Organization role of Organization Administrator will receive is labeled JSON Response (Organization Administrator):.

Retrieve All Users

To retrieve all users in the Organization in which your API user account resides, use the following query:

GET /v3/security/users

JSON Response:

{
    "data": [
        {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "JMS",
            "owner": "Demo Organization",
            "systemRrole": "Administrator"
        },
        {
            "id": 2,
            "userName": "[email protected]",
            "firstName": "Pat",
            "lastName": "Jones",
            "pseudonym": "patjones",
            "owner": "Demo Organization",
            "systemRrole": "User"
        },
        {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization",
            "systemRrole": "Api User"
        },
        {...}
    ],
    "status": "Success"
}

JSON Response (Organization Administrator):

{
    "data": [
        {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "JMS",
            "owner": "Demo Organization",
            "lastLogin": "2022-09-07T12:19:42Z",
            "lastPasswordChange": "2022-08-04T16:24:25Z",
            "uiTheme": "Light",
            "jobFunction": "Threat Intelligence",
            "jobRole": "Analyst",
            "termsAccepted": true,
            "logoutIntervalMinutes": 240,
            "systemRole": "Administrator",
            "ownerRoles": {
                "Demo Organization": "Organization Administrator",
                "Demo Community": "Director",
                "Demo Source": "Director"
            },
            "disabled": false,
            "locked": false,
            "passwordResetRequired": false,
            "twoFactorResetRequired": false
        },
        {
            "id": 2,
            "userName": "[email protected]",
            "firstName": "Pat",
            "lastName": "Jones",
            "pseudonym": "patjones",
            "owner": "Demo Organization",
            "lastLogin": "2022-09-07T11:27:12Z",
            "lastPasswordChange": "2022-09-02T09:13:02Z",
            "uiTheme": "Dark",
            "jobFunction": "Incident Response",
            "jobRole": "Analyst",
            "termsAccepted": true,
            "logoutIntervalMinutes": 30,
            "systemRole": "User",
            "ownerRoles": {
                "Demo Organization": "Standard User",
                "Demo Community": "Director",
                "Demo Source": "Director"
            },
            "disabled": false,
            "locked": false,
            "passwordResetRequired": false,
            "twoFactorResetRequired": false
        },
        {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization",
            "lastPasswordChange": "2022-05-03T14:51:55Z",
            "termsAccepted": false,
            "logoutIntervalMinutes": 30,
            "systemRole": "Administrator",
            "ownerRoles": {
                "Demo Organization": "Organization Administrator",
                "Demo Community": "Director",
                "Demo Source": "Director"
            },
            "disabled": false,
            "locked": false,
            "passwordResetRequired": false,
            "twoFactorResetRequired": false
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single User

To retrieve a specific user in the Organization in which your API user account resides, use a query in the following format:

GET /v3/security/users/{userId}

For example, the following query will return information about the user with ID 3:

GET /v3/security/users/3

JSON Response:

{
    "data": {
        "id": 3,
        "userName": "11112222333344445555",
        "firstName": "John",
        "lastName": "Smith",
        "pseudonym": "jsmithAPI",
        "owner": "Demo Organization",
        "systemRole": "Api User"
    },
    "status": "Success"
}

JSON Response (Organization Administrator):

{
    "data": {
        "id": 3,
        "userName": "11112222333344445555",
        "firstName": "John",
        "lastName": "Smith",
        "pseudonym": "jsmithAPI",
        "owner": "Demo Organization",
        "lastPasswordChange": "2022-05-03T14:51:55Z",
        "termsAccepted": false,
        "logoutIntervalMinutes": 30,
        "systemRole": "Administrator",
        "ownerRoles": {
            "Demo Organization": "Organization Administrator",
            "Demo Community": "Director",
            "Demo Source": "Director"
        },
        "disabled": false,
        "locked": false,
        "passwordResetRequired": false,
        "twoFactorResetRequired": false
    },
    "status": "Success"
}

Request Additional Fields

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Users

Attention

Only API users with an Organization role of Organization Administrator can update users.

The basic format for updating a user is:

PUT /v3/security/users/{userId}
{
    {updatedField}: {updatedValue}
}

For example, the following query will disable and lock the account for the user with ID 11:

PUT /v3/security/users/11
{
    "disabled": true,
    "locked": true
}

JSON Response

{
    "data": {
        "id": 11,
        "userName": "[email protected]",
        "firstName": "Donald",
        "lastName": "Jefferson",
        "owner": "Demo Organization",
        "lastPasswordChange": "2022-08-30T12:45:17Z",
        "uiTheme": "Light",
        "termsAccepted": true,
        "logoutIntervalMinutes": 30,
        "systemRole": "User",
        "ownerRoles": {
            "Demo Organization": "Standard User",
            "Demo Community": "Director",
            "Demo Source": "Director"
        },
        "disabled": true,
        "locked": true,
        "passwordResetRequired": false,
        "twoFactorResetRequired": false
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a PUT request for the users object.

Note

Updating users in bulk is not supported at this time.

Delete Users

Attention

Only API users with an Organization role of Organization Administrator can delete users.

The basic format to delete a user is:

DELETE /v3/security/users/{userId}

For example, the following query will delete the user with ID 10:

DELETE /v3/security/users/10

JSON Response

{
    "message": "Deleted",
    "status": "Success"
}

Note

Deleting users in bulk is not supported at this time.