ThreatX API Reference for Administrators :: ThreatX Product Documentation

Introduction

The ThreatX platform uses a RESTful API and supports a full set of application capabilities that can be used ad-hoc, in scripts, and in automation tool sets. Common uses include creating and managing user accounts, provisioning new sites to be protected, and managing certificates.

To access the ThreatX API, you must know your tenant name and you must have an API key to authenticate and create a session token. See Generating and revoking API keys

For details about the API endpoints and commands, see the API Reference Guide (requires a ThreatX account to access).

The login command uses an API key to return a temporary access token that authenticates your session.

The api_key, created within the ThreatX user interface ( Settings API Keys ), is used within the request for the api_token parameter. The response then provides a unique and temporary access_token string to be used in further endpoint commands.

Table 1. Login Command Object
Parameters	Type
`“command”: “login”`	String
`“api_token”: ”<api_key>”`	String

📌 Example 1. Login Command Usage

Request

$ curl {url-txapi}/login \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
    "command": "login",
    "api_token": "<api_key>"
}
EOF

Response

{
"Ok": {
    "status": true,
    "token": "<access_token>"
  }
}

List Customers

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

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

📌 Example 2. List Command Usage

Request

$ curl {url-txapi}/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 3. Command Object
Parameters	Type
`“command”: “update”`	String
`“token”: “<access_token>”`	String
`“name”: “<tenant_name>”`	String
`“customer”: {}`	CustomerObject

Table 4. 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 5. 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 3. Update Command Usage

Request

$ curl {url-txapi}/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." }

List Channels

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

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

📌 Example 4. List Command Usage

Request

$ curl {url-txapi}/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

The update command updates a specified channel.

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

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

Table 9. 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 5. 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."}