Splunk® Data Stream Processor

Getting Data In

Acrobat logo Download manual as PDF


On April 3, 2023, Splunk Data Stream Processor will reach its end of sale, and will reach its end of life on February 28, 2025. If you are an existing DSP customer, please reach out to your account team for more information.
This documentation does not apply to the most recent version of Splunk® Data Stream Processor. For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

Create and manage DSP HEC tokens with the Ingest REST API

DSP HEC Tokens are entities that let logging agents and HTTP clients connect to DSP. 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 will not work with DSP HEC. You must create a new token for DSP HEC.

  • DSP HEC token names must be lower case and must not contain special characters.
  • DSP HEC token names must be 4-36 characters in length.
  • The user must have the ingest.admin role for the tenant.

The generated DSP HEC token is only returned once. You can't retrieve the token at a later date.

You can create DSP HEC tokens with either the Ingest REST API or with SCloud. See the Splunk Data Stream Processor REST API Reference for more information about the DSP REST API. See Get started with SCloud for more information about SCloud.

You must have SCloud version 2.0.0 or higher to use SCloud to generate DSP HEC tokens.

Create a DSP HEC token with the Ingest REST API

The following example demonstrates how to use the Ingest REST API to create a DSP HEC token.

curl -X POST "https://<DSP_HOST>:31000/default/ingest/v1beta2/collector/tokens" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
          "name": "<dsphec-token-name>"
         }'

The generated DSP HEC token is only returned once. You can't retrieve the token at a later date.

A typical response when you create a DSP HEC token using a POST request looks like this:

{
  "tenant": "default",
  "name": "<dsphec-token-name>"
  "token": "<dsphec-token>" ,
  "createUserID": "name@example.com",
  "createdAt": "2020-01-09T06:46:50.129Z",
  "last_modified_by": "name@example.com",
  "last_modified_at": "2020-01-09T06:46:50.129Z"
}

Verify that the DSP HEC token is working in your DSP pipeline

You can verify that the DSP HEC token is working in your DSP pipeline with the pipeline preview.

  1. Create a new pipeline in DSP. See Create a pipeline using the Canvas Builder for more information on creating a new pipeline.
  2. Add Read from Splunk Firehose as your data source.
  3. Click Start Preview.
  4. Use your HTTP client to send the following HTTP request:
    curl -X POST "https://<DSP_HOST>:31000/services/collector/event" \
       -H "Authorization: Splunk <dsphec-token>" \
       -d '{
       "event": "Hello, world!",
       "sourcetype": "manual"
    }'

You can now see the test event in the pipeline preview.

Update a DSP HEC token by name with the Ingest REST API

The following example demonstrates how to use the Ingest REST API to update a DSP HEC token.

curl -X PUT "https://<DSP_HOST>:31000/default/ingest/v1beta2/collector/tokens/<name>" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d {
          "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 a PUT request looks like this:

{
    "tenant": "default",
    "name": "<dsphec-token-name>",
    "description": "A token for the clients in us-west datacenter 1",
    "created_by": "name@example.com",
    "created_at": "2020-03-27T23:45:54.072714Z",
    "last_modified_by": "name@example.com",
    "last_modified_at": "2020-03-28T18:42:03.921962Z"
}

Get the MetaData for a DSP HEC token by name with the Ingest REST API

The following example demonstrates how to use the Ingest REST API to get the MetaData from a DSP HEC token.

curl -X GET "https://<DSP_HOST>:31000/default/ingest/v1beta2/collector/tokens/<name>" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json"

A typical response when you request the MetaData for a DSP HEC token using a GET request looks like this:

{
    "tenant": "default",
    "name": "<dsphec-token-name>",
    "created_by": "name@example.com",
    "created_at": "2020-03-27T23:45:54.072714Z",
    "last_modified_by": "name@example.com",
    "last_modified_at": "2020-03-27T23:45:54.072714Z"
}

List all DSP HEC tokens with the Ingest REST API

The following example demonstrates how to use the Ingest REST API to list all DSP HEC tokens.

curl -X GET "https://<DSP_HOST>:31000/default/ingest/v1beta2/collector/tokens?limit=<limit>&offset=<offset>" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json"

A typical response when you list all DSP HEC tokens using a GET request looks like this:

{
  "tokens": [
    {
      "tenant": "default",
      "name": "<dsphec-token-name-01>",
      "createdAt": "2020-01-09T06:46:50.129Z",
      "createUserID": "user@example.com"
    },
    {
      "tenant": "default",
      "name": "<dsphec-token-name-02>",
      "createdAt": "2020-01-09T06:49:23.104Z",
      "createUserID": "user@example.com"
    }
  ]
}

Delete a DSP HEC token by name with the Ingest REST API

The following example demonstrates how to use the Ingest REST API to delete a specific DSP HEC token.

curl -X DELETE "https://<DSP_HOST>:31000/default/ingest/v1beta2/collector/tokens/<name>" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json"

Delete all DSP HEC tokens with the Ingest REST API

The following example demonstrates how to use the Ingest REST API to delete all DSP HEC tokens.

curl -X DELETE "https://<DSP_HOST>:31000/default/ingest/v1beta2/collector/tokens" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json"
Last modified on 03 July, 2020
PREVIOUS
Send events to a DSP data pipeline using the DSP HTTP Event Collector
  NEXT
Create and manage DSP HEC tokens with SCloud

This documentation applies to the following versions of Splunk® Data Stream Processor: 1.1.0


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters