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; however, they may not perform these actions for users whose System role is Administrator or Operations Administrator. API users with any other Organization role can only retrieve users.

Endpoint Options

Available Fields

Send the following request to retrieve a list of fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/security/users endpoint:

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 to the /v3/security/users endpoint:

Field

Description

Type

Required for Creation?

Updatable?

customTqlTimeout

The maximum amount of time, in milliseconds, that ThreatConnect Query Language (TQL) queries made by the user will be allowed to run before timing out

Integer

FALSE

TRUE

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 [1]

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

TRUE

password [2]

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 [3]

The user’s System role

String

TRUE

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 [4]

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

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/security/users endpoint:

OPTIONS /v3/security/users/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/security/users endpoint:

OPTIONS /v3/security/users/tql

Create Users

Attention

Only API users with an Organization role of Organization Administrator can create users. However, they may not create users whose System role is Administrator or Operations Administrator.

The following example illustrates the basic format for creating a user:

POST /v3/security/users
Content-Type: application/json

{
    "firstName": "John",
    "lastName": "Smith",
    "userName": "[email protected]",
    "password": "Password1!",
    "owner": "Demo Organization",
    "ownerRoles": {
        "Demo Organization": "Standard User"
    },
    "systemRole": "User"
}

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

POST /v3/security/users
Content-Type: application/json

{
    "firstName": "Herschel",
    "lastName": "Hodges",
    "userName": "[email protected]",
    "password": "Password1!",
    "owner": "Demo Organization",
    "ownerRoles": {
        "Demo Organization": "Standard User"
    },
    "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 to the /v3/security/users endpoint.

Note

Creating users in bulk is not supported at this time.

Retrieve Users

When retrieving data for 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

Send the following request to retrieve data for all users in the Organization in which your API user account resides:

GET /v3/security/users

JSON Response:

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

Retrieve a Specific User

Send a request in the following format to retrieve data for a specific user in the Organization in which your API user account resides:

GET /v3/security/users/{userId}

For example, the following request will retrieve data for the user whose ID is 3:

GET /v3/security/users/3

JSON Response:

{
    "data": {
        "id": 3,
        "userName": "11112222333344445555",
        "firstName": "John",
        "lastName": "Smith",
        "pseudonym": "jsmithAPI",
        "owner": "Demo Organization"
    },
    "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"
}

Update Users

Attention

Only API users with an Organization role of Organization Administrator can update users. However, they may not update users whose System role is Administrator or Operations Administrator.

The following example illustrates the basic format for updating a user:

PUT /v3/security/users/{userId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will disable and lock the account for the user whose ID is 11:

PUT /v3/security/users/11
Content-Type: application/json

{
    "disabled": true,
    "locked": true
}

JSON Response

{
    "data": {
        "id": 11,
        "userName": "[email protected]",
        "firstName": "Donald",
        "lastName": "Jefferson",
        "pseudonym": "DonJ",
        "owner": "Demo Organization",
        "lastPasswordChange": "2022-08-30T12:45:17Z",
        "uiTheme": "Light",
        "jobFunction": "Threat Intelligence",
        "jobRole": "Analyst",
        "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"
}

In this next example, the request will update the owner role for the user whose ID is 12 in their Organization:

PUT /v3/security/users/12
Content-Type: application/json

{
    "owner": "Demo Organization",
    "ownerRoles": {
        "Demo Organization": "Organization Administrator"
    }
}

JSON Response

{
    "data": {
        "id": 12,
        "userName": "[email protected]",
        "firstName": "Herschel",
        "lastName": "Hodges",
        "owner": "Demo Organization",
        "lastPasswordChange": "2024-07-09T14:35:05Z",
        "uiTheme": "Light",
        "termsAccepted": false,
        "logoutIntervalMinutes": 30,
        "systemRole": "User",
        "ownerRoles": {
            "Demo Organization": "Organization Administrator",
            "Demo Community": "Editor",
            "Demo Source": "Editor"
        },
        "disabled": false,
        "locked": false,
        "passwordResetRequired": true,
        "twoFactorResetRequired": true
    },
    "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 to the /v3/security/users endpoint.

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. However, they may not delete users whose System role is Administrator or Operations Administrator.

Send a request in the following format to delete a user:

DELETE /v3/security/users/{userId}

For example, the following request will delete the user whose ID is 10:

DELETE /v3/security/users/10

JSON Response

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

Note

Deleting users in bulk is not supported at this time.