Subscribe to the Taegis™ VDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Using the API through JSON Web Tokens (JWT)

This article describes the steps needed to fully automate management of the product’s licenses and public API through the use of JSON Web Tokens.

JSON Web Tokens are an open industry standard formalized through RFC 7519 that can be used with Secureworks® Taegis™ VDR’s APIs in order to automate license management (Management API) and regular product activity through its OpenAPI (Impersonation API).

In order to obtain access to the API JWT infrastructure, you will need to:

Overview of the JWT Setup Flow


JWT Flow Diagram

Generating a Secure Set of Keys

The key format that we require for your JWT is ECDSA keys using curve secp521r1.

As an example, you can generate these using the following openssl commands, but make sure to adapt this to your own key management policy so that they are handled in a secure way (in this example the private key will be generated on disk, in the directory that you are in).

openssl ecparam -genkey -name secp521r1 -noout -out mgt-api-private.pem

openssl ec -in mgt-api-private.pem -pubout -out mgt-api-public.pem

These commands will need to be repeated for the impersonation API to obtain a secondary set of public/private keys.


Make sure that the openssl binary you are using to generate the keys is really provided by the Openssl package and not by libressl or another equivalent. The key format might differ, which would result in invalid tokens being generated.

Send the Public Key File to Secureworks

Once you’ve managed to generate the set of keys, send us the public part only. In the above example that would be the license-api-public.pem file.

You can send this keypart directly by email to vdr@secureworks.com.

Obtain an Issuer and CID from Secureworks

Once obtained, we will set up your public key file on our end, and generate two specific base64-encoded data elements that you will need to use in your code as part of your token signature mechanism. These two elements are the issuer (very long) and the CID (relatively short).


The issuer string sent out by Secureworks is itself a JWT token (hence its length) which could cause confusion: if you try to use this token directly towards our APIs, it will not work. The issuer string that you were provided has to be made part of your own newly generated tokens, that are then signed with your own private key as shown in the code examples below. Simply put: just treat the issuer Secureworks provides as a simple string of characters.

Use the Issuer and CID to Sign API Messages

Using JWT is well documented with many language-specific examples out there.

The following very basic example is provided in Python as a starting mechanism for you to validate your use case before implementing it in your production system.

Note that there are two examples, one for each API (impersonation API and management API), with distinct parameters and keys.


Placeholders that you have to fill in are provided between brackets <>.

Example Using the Impersonation API

import jwt

# Configuration
with open("/path/to/impersonation-api-private.pem", "r") as fp:
    sign_key = fp.read()
issuer = "<Base 64 string provided by Secureworks>"
client_id = "<Base 64 string provided by Secureworks>"
instance_name = "<your instance name>" # Instance name is the subdomain in your URL
impersonation_user_id = 123 # Specific user id we will perform the request as (impersonate)

token = jwt.encode({
    "iss": issuer,
    "iat": time(),
    "exp": time() + 60,
    "aud": instance_name,
    "sub": "user:" + impersonation_user_id,
    "cid": client_id,
    "scp": ["read_only", "full_access"],
}, sign_key, algorithm="ES512").decode("utf-8")

# ...

headers = {"Authorization": f"Bearer {token}"}

# Do the request

The API Endpoints that can be targeted are exactly the same as provided in the Swagger documentation file of your own instance, accessible at

https://<YOUR INSTANCE>.vdr.secureworks.com/api/v2/spec#/


On this page: