Create and manage DSP HEC tokens through the Splunk Cloud Services CLI

DSP HEC tokens are entities that let logging agents and HTTP clients connect to the . When the clients connect, they present this token. If the DSP HEC receives a valid token, it accepts the connection, and the client delivers its payload of application events in JSON format.

Splunk HEC tokens do not work with DSP HEC. You must create a new token for DSP HEC.

You can create DSP HEC tokens using either the Splunk Cloud Services CLI or the Ingest service. The following examples demonstrate how to create, retrieve, update, and delete DSP HEC tokens using the Splunk Cloud Services CLI. See Create and manage DSP HEC tokens through the Ingest service for information about using the Ingest service.

Prerequisites

Before you can create and manage DSP HEC tokens using the Splunk Cloud Services CLI, you must have Splunk Cloud Services CLI version 3.0.0 or higher configured to send data to the . See Get started with the Splunk Cloud Services CLI in the Install and administer the Data Stream Processor manual for more information.

Create a DSP HEC token with the Splunk Cloud Services CLI

When you create a DSP HEC token, you assign a name to it. The token name must be 4-36 characters in length, and cannot contain uppercase letters or special characters.

The following example demonstrates how to use the Splunk Cloud Services CLI to create a DSP HEC token. Replace <dsp-hec-token-name> with the name that you want to assign to the DSP HEC token.

./scloud ingest post-collector-tokens --name <dsp-hec-token-name> --description "An example token"

The generated DSP HEC token is only returned once. You can't retrieve the token at a later date. Make sure to keep track of the returned token value.

A typical response when you create a DSP HEC token using the Splunk Cloud Services CLI looks like this:

{
    "ack_enabled": false,
    "allow_query_string_auth": false,
    "created_at": "2020-04-24T19:31:17.578536102Z",
    "created_by": "name@example.com",
    "description": "An example token",
    "disabled": false,
    "index": "",
    "last_modified_at": "2020-04-24T19:31:17.578536102Z",
    "last_modified_by": "name@example.com",
    "name": "<dsp-hec-token-name>",
    "source": "",
    "sourcetype": "",
    "tenant": "default",
    "token": "<dsp-hec-token>"
}

You can also create tokens that specify default values for source, sourcetype, and index. See Use the metadata of the DSP HEC token to specify default values for more information.

Verify that the DSP HEC token is working in your pipeline

To verify that the DSP HEC token is working, start a preview session in DSP and send a test event to your pipeline using the token.

1. In DSP, create a pipeline that starts with the Splunk DSP Firehose source function.
2. Click the Start Preview icon ().
3. Use your HTTP client to send the following HTTP request, where <DSP_HOST> is the name of your DSP tenant and <dsp-hec-token> is your DSP HEC token:

   curl -X POST "https://<DSP_HOST>:31000/services/collector/event" \
      -H "Authorization: Splunk <dsp-hec-token>" \
      -d '{
      "event": "Hello, world!",
      "sourcetype": "manual"
   }'

You can see the test event in the Preview Results pane.

Update a DSP HEC token by name with the Splunk Cloud Services CLI

The following example demonstrates how to use the Splunk Cloud Services CLI to update a DSP HEC token. Replace <dsp-hec-token-name> with the name of your DSP HEC token.

The generated DSP HEC token is only returned when the token is created. You cannot see the generated token value when you update the tokens.

./scloud ingest put-collector-token --token-name <dsp-hec-token-name> --description "A token for the clients in us-west datacenter 1"

A typical response when you update the metadata for a DSP HEC token using the Splunk Cloud Services CLI looks like this:

{
    "ack_enabled": false,
    "allow_query_string_auth": false,
    "created_at": "2020-04-24T19:31:17.578536Z",
    "created_by": "name@example.com",
    "description": "A token for the clients in us-west datacenter 1",
    "disabled": false,
    "index": "",
    "last_modified_at": "2020-04-24T19:39:11.921962Z",
    "last_modified_by": "name@example.com",
    "name": "<dsp-hec-token-name>",
    "source": "",
    "sourcetype": "",
    "tenant": "default"
}

You can also update the default values for source, sourcetype, and index in the token. See Use the metadata of the DSP HEC token to specify default values for more information.

Get the metadata for a DSP HEC token by name with the Splunk Cloud Services CLI

The following example demonstrates how to use the Splunk Cloud Services CLI to get the metadata from a DSP HEC token. Replace <dsp-hec-token-name> with the name of your DSP HEC token.

The generated DSP HEC token is only returned when the token is created. You cannot see the generated token value when you get the metadata for the tokens.

./scloud ingest get-collector-token --token-name <dsp-hec-token-name>

A typical response when you request the metadata for a DSP HEC token using the Splunk Cloud Services CLI looks like this:

{
    "ack_enabled": false,
    "allow_query_string_auth": false,
    "created_at": "2020-04-24T19:31:17.578536102Z",
    "created_by": "name@example.com",
    "description": "A token for the clients in us-west datacenter 1",
    "disabled": false,
    "index": "",
    "last_modified_at": "2020-04-24T19:31:17.578536102Z",
    "last_modified_by": "name@example.com",
    "name": "<dsp-hec-token-name>",
    "source": "",
    "sourcetype": "",
    "tenant": "default"
}

List all DSP HEC tokens with the Splunk Cloud Services CLI

The following example demonstrates how to use the Splunk Cloud Services CLI to list all DSP HEC tokens.

./scloud ingest list-collector-tokens

Optionally, you can limit the number of returned tokens by including the --limit and --offset flags. Using the following example, set <limit> to the number of DSP HEC tokens to return, and set <offset> to the number of tokens that you want to skip ahead. For instance, setting <limit> to 2 and <offset> to 3 returns the 4th and 5th tokens in your tenant.

The generated DSP HEC token is only returned when the token is created. You cannot see the generated token value when you list the tokens.

./scloud ingest list-collector-tokens --limit <limit> --offset <offset>

A typical response when you list all DSP HEC tokens looks like this:

[
    {
        "ack_enabled": false,
        "allow_query_string_auth": false,
        "created_at": "2020-04-24T19:31:17.578536Z",
        "created_by": "name@example.com",
        "description": "An example token",
        "disabled": false,
        "index": "",
        "last_modified_at": "2020-04-24T19:39:11.921962Z",
        "last_modified_by": "name@example.com",
        "name": "<dsp-hec-token-name-01>",
        "source": "",
        "sourcetype": "",
        "tenant": "default"
    },
    {
        "ack_enabled": false,
        "allow_query_string_auth": false,
        "created_at": "2020-04-07T18:18:29.430245Z",
        "created_by": "name@example.com",
        "description": "A second example token",
        "disabled": false,
        "index": "",
        "last_modified_at": "2020-04-07T18:18:29.430245Z",
        "last_modified_by": "name@example.com",
        "name": "<dsp-hec-token-name-02>",
        "source": "",
        "sourcetype": "",
        "tenant": "default"
    }
]

Delete a DSP HEC token by name with the Splunk Cloud Services CLI

The following example demonstrates how to use the Splunk Cloud Services CLI to delete a specific DSP HEC token. Replace <dsp-hec-token-name> with the name of your DSP HEC token.

./scloud ingest delete-collector-token --token-name <dsp-hec-token-name>

Delete all DSP HEC tokens with the Splunk Cloud Services CLI

The following example demonstrates how to use the Splunk Cloud Services CLI to delete all DSP HEC tokens.

./scloud delete-all-collector-tokens