Tenants and Channels

Tenants vs. Channels

Tenants are organizational units. Administrator user accounts are provisioned within these tenants. Once provisioned, users can view protected sites, attack heuristics, real-time data, and other configuration information.

Alternatively, you can have your ThreatX platform organized by channels, where a channel can contain multiple tenants. If you have channels, you can administer all users and sites within the tenants and add tenants as needed. See: Channels

Customers

List Customers

The list command returns the details of all tenants authorized for the current API access token.

Table 1. Command Object
Parameters	Type
`“command”: “list”`	String
`“token”: “<access_token>”`	String

📌 Example 1. List Command Usage

Request

$ curl api.threatx.com/tx_api/v2/customers \
  --header 'Content-Type: application/json' \
   --data @- <<EOF
{
  "command": "list",
  "token": "<access_token>"
}
EOF

Replace <access_token> with your access token from the last command.

Response

{
"Ok": [
   {
   "name": "testco",
   "contact_email": "alice@testco.com",
   "description": "Tesco tenant",
   "active": true,
   "autoblock_threshold": 70,
   "autoblock_timeout": 3600,
   "block_embargo": true,
   "ssl_ciphers": null,
   "notify_threshold": 100,
   "sso": null,
   "allow_super_admin_users": true,
   "allow_channel_admin_users": true,
   "tenant_admin_default": null,
   "uuid": "<tenant_uuid>"
   }
  ]
}

Update Customer

The update command updates a specified tenant.

The SSO object is used to configure the SSO parameters. All other parameters to the customer object should not be modified when configuring SSO.

Table 2. Command Object
Parameters	Type
`“command”: “update”`	String
`“token”: “<access_token>”`	String
`“name”: “<tenant_name>”`	String
`“customer”: {}`	CustomerObject

Table 3. Customer Object
Parameters	Type
`“name”: “<tenant_name>”`	String
`“contact_email”: “<email_address>”`	String
`“description”: “<key_description>”`	String
`“active”: true / false`	Boolean
`“autoblock_threshold”: <entity_risk>`	Integer
`“autoblock_timeout”: <timeout_seconds>`	Integer
`“sso”: {}`	SSO Object

Table 4. SSO Object
Parameters	Type	Description
`enabled`	Boolean	When true, users belonging to the tenant are allowed to sign in to the ThreatX user interface using SSO.
`required`	Boolean	When true, users are required to use SSO to sign in to the ThreatX user interface.
`saml_metadata_url: “<saml_url>”`	String	IDP metadata URL or file. See the Prerequisites.

📌 Example 2. Update Command Usage

Request

$ curl api.threatx.com/tx_api/v2/customers \
  --header 'Content-Type:  application/json' \
   --data @- <<EOF
{
     "command": "update",
     "token": "<login_token>",
     "name": "testco",
     "customer": {
         "name": "testco",
         "contact_email": "alice@testco.com",
         "description": "Testco tenant",
         "active": true,
         "autoblock_threshold": 70,
         "autoblock_timeout": 3600,
         "block_embargo": true,
         "ssl_ciphers": null,
         "notify_threshold": 100,
         "allow_super_admin_users": true,
         "allow_channel_admin_users": true,
         "tenant_admin_default": null,
         "sso": {
             "enabled": true,
             "required": false,
             "saml_metadata_url": "https://login.microsoftonline.com/daad3805-fde6-4334-817f-82c723533123/federationmetadata/2007-06/federationmetadata.xml"
          }
    }
}
EOF

Response

{ "Ok": "testco updated." }

Channels

List Channels

The list command of the channels endpoint returns the details of all channels authorized for the current API access token.

Table 5. Command Object
Parameters	Type
`“command”: “list”`	String
`“token”: “<access_token>”`	String

📌 Example 3. List Command Usage

Request

$ curl api.threatx.com/tx_api/v2/channels \
  -H 'Content-Type: application/json' \
  --data @- <<EOF
{
    "command": "list",
    "token":" "<access_token>"
}
EOF

Response

{
  "Ok": [
    {
      "name": "test_channel",
       "require_totp_setup": null,
       "uuid": "81815E73-ABB9-4533-977B-93964B8AAB73",
       "sso": null
     }
  ]
}

Update Channels using the API

The update command updates a specified channel.

Table 6. Command Object
`Parameters`	Type
`command`	String
`token`	String
`channel`	Channel Object

Table 7. Channel Object
Parameter	Type
`name`	String
`sso`	SSO Object

Table 8. SSO Object Attributes
Name	Type	Description
`enabled`	Boolean	When true, users belonging to the channel are allowed to sign in to the ThreatX user interface using SSO.
`required`	Boolean	When true, users in the channel are required to use SSO to sign in to the ThreatX user interface.
`saml_metadata_url`	String	IDP metadata URL or file. See the Prerequisites.

📌 Example 4. Update Command Usage

Request

$ curl {url-txapi}/channels \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
    "command": "update",
     "token": "<login_token>",
     "channel": {
     "name": "test_channel",
     "sso": {
        "enabled": true,
        "required": false,
        "saml_metadata_url": "https://login.microsoftonline.com/daad3805-fde6-4334-817f-82c723533123/federationmetadata/2007-06/federationmetadata.xml"
       }
     }
}
EOF

Response

{"Ok": "Channel: test_channel updated."}