Manage HTTP Event Collector (HEC) tokens in Splunk Cloud Platform

The HTTP Event Collector (HEC) lets you send data and application events to your Splunk deployment over HTTP protocol using token-based authentication. You can use the Admin Config Service (ACS) API to create and manage HEC tokens for your Splunk Cloud Platform deployment programmatically.

For more information on HEC tokens, see How the Splunk platform uses HEC tokens to get data in, in the Getting Data In manual.

The Terraform Provider for Splunk Cloud Platform supports ACS HEC token management operations, including retry of failed HEC token operations. To access the Splunk Cloud Platform Terraform Provider (terraform-provider-scp), see the Terraform Registry. For more information on retry of failed HEC operations, see Retry failed operations in Splunk Cloud Platform.

Requirements

To manage HEC tokens using the ACS API:

• Your role must have the capabilities required to access the ACS API endpoint. The sc_admin role has all required capabilities by default. For a list of required capabilities, see Manage ACS API access with capabilities.
• You must have Splunk Cloud Platform version 8.1.2101 or higher.
• Your deployment must have one or more separate search heads or a search head cluster. ACS is not supported on single instance deployments.

The ACS API supports HEC token management on both Victoria Experience and Classic Experience.

Set up the ACS API

Before using the ACS API, you must download the ACS Open API 3.0 specification, which includes the parameters, codes, and other data you need to work with the ACS API. You must also create an authentication token in Splunk Cloud Platform for use with ACS endpoint requests. For details on how to set up the ACS API, see Set up the ACS API.

Manage HEC tokens using the ACS API

The following instructions show you how to create and manage HEC tokens in Splunk Cloud Platform using the ACS API. These instructions apply to Splunk Cloud Platform deployments on both Victoria Experience and Classic Experience.

View existing HEC tokens

To list existing HEC tokens in your environment, send an HTTP GET request to the following endpoint:

admin.splunk.com/{stack}/adminconfig/v2/inputs/http-event-collectors

For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/inputs/http-event-collectors' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiw...' \
--header 'Content-Type: application/json' \

The request returns token names, default hosts, default indexes, and token values. For example:

{
   "http-event-collectors": [
       {
           "spec": {
               "allowedIndexes": [
                   "main",
                   "summary"
               ],
               "defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
               "defaultIndex": "main",
               "defaultSource": "",
               "defaultSourcetype": "",
               "disabled": true,
               "name": "hec-token-name",
               "useACK": true
           },
           "token": "9803a48f-b733-4106-8a3f-871c..."
       }
   ]
}

By default, the list HEC tokens request returns a maximum count of 30 tokens. To change the count, you can specify a count value up to a maximum of 100. A count value of 0 lists all HEC tokens.

If you have more than 100 tokens, you can specify an offset value to list additional tokens. For example, to list tokens 100-200, specify an offset value of 100. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/inputs/http-event-collectors?offset=100&count=100'

Create a new HEC token

To create a new HEC token, send an HTTP POST request to the inputs/http-event-collectors endpoint. The request payload must include a unique token name and a default index. If the default index is not specified, ACS sets the default index to default.

For defaultHost, if you do not specify a value, or specify an invalid host, Splunk Cloud Platform automatically sets the value to the search head instance name. If your deployment has more than one search head, such as in a search head cluster, Splunk Cloud Platform chooses a search head name randomly.

You can optionally specify the useACK option, as a boolean (true/false) value, to enable or disable indexer acknowledgement. You can also optionally use the token option to specify an already existing HEC token value.

Splunk Cloud Platform currently supports indexer acknowledgement for Amazon Web Services (AWS) Kinesis Firehose only.

Make sure the specified default index exists on your system. Specifying an index that does not exist can cause data loss.

For example:

curl -X POST 'https://admin.splunk.com/wacky-walrus-f90/adminconfig/v2/inputs/http-event-collectors' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiw...' \
--header 'Content-Type: application/json' \
--data-raw '{
   "allowedIndexes": [
       "main",
       "summary"
   ],
   "defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
   "defaultIndex": "main",
   "defaultSource": "",
   "defaultSourcetype": "",
   "disabled": false,
   "name": "testhec",
   "useACK": false
}'

The request returns the token name, which you use to retrieve the token value, and a 202 status code, which indicates the request was accepted, but token creation is still in progress due to the asynchronous token creation process. For example:

{
  "http-event-collector": {
    "spec": {
      "name": "testhec"
    }
  }
}

To retrieve the token value, you must send a GET request to the inputs/http-even-collectors/{hec-token-name} endpoint. See Confirm token creation and retrieve token value.

For endpoint details, see inputs/http-event-collectors in the ACS endpoint reference.

Confirm token creation and retrieve token value

To confirm that your HEC token was created successfully and to retrieve the token value, send an HTTP GET request to the inputs/http-even-collectors{hec-token-name} endpoint, specifying the token name. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/inputs/http-event-collectors/testhec'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi…'

If the request returns code": "404-hec-not-found", index creation is still in progress. For example:

{
   "code": "404-hec-not-found",
   "message": "Hec not found"
}

It might take a few minutes for the token creation process to complete. Repeat the GET request until the status code is 200. When token creation is complete, the request returns the token configuration details and the token value in the response body. For example:

{
  "http-event-collector": {
    "spec": {
      "allowedIndexes": [
        "main",
        "summary"
      ],
      "defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
      "defaultIndex": "final_test_1",
      "defaultSource": "",
      "defaultSourcetype": "",
      "disabled": false,
      "name": "testhec",
      "useAck": false
    },
    "token": "a8d0472c-aa9e-4f35-aadb-8a35..."
  }
}

Update an HEC token

To update an HEC token, send an HTTP PATCH request or an HTTP PUT request to the inputs/http-event-collectors/{hec-token-name} endpoint, specifying the HEC token name and updated parameters.

A PATCH request changes only those parameter values that you specify and does not change any existing parameter values that you do not specify.

A PUT request overwrites all existing parameter values and restores to default any parameter value that you do not specify in the request. A PUT request creates a new token if a token with the specified name does not exist.

You cannot update the token value itself.

For example, the following PATCH request changes the disabled parameter to true, which disables the HEC token.

curl -X PATCH 'https://admin.splunk.com/wacky-walrus-f90/adminconfig/v2/inputs/http-event-collectors/testhec' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiw...' \
--header 'Content-Type: application/json' \
--data-raw '{
   "allowedIndexes": [
       "main",
       "summary"
   ],
   "defaultHost": "",
   "defaultIndex": "main",
   "defaultSource": "",
   "defaultSourcetype": "",
   "disabled": true,
   "name": "testhec"
}'

The request returns a 202 status code, which indicates the request has been accepted, but the update is still in progress due to the asynchronous HEC token update process.

To confirm the HEC token update is complete, send an HTTP GET request to the inputs/http-event-collectors/{hec-token-name} endpoint. Repeat the GET request until the response body shows the updated configuration values.

You can also verify your token updates inside the Splunk Web UI, as follows:

1. In Splunk Web, click Data Inputs > Http Event Collector.
2. Find the HEC token in the list of tokens, and confirm that token parameters have been updated as expected.

Delete an HEC token

To delete an HEC token, send an HTTP DELETE request to the the inputs/http-event-collectors/{hec-token-name} endpoint, specifying the name of the HEC token you want to delete. For example:

curl -X DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/inputs/http-event-collectors/hec-token-name'

For endpoint details, see inputs/http-event-collectors/{hec-token-name} in the ACS endpoint reference.

Manage HEC tokens using Splunk Cloud Classic non-ACS endpoints (old method)

This section shows examples of how you can manage HEC tokens using Splunk Cloud Classic endpoints.

You can now manage HEC tokens on Classic Experience using the ACS API, without running operations directly against Splunk Cloud Classic endpoints. The Splunk Cloud Classic endpoints shown in this section are for reference only. For more information, see Manage HEC tokens using the ACS API.

View existing HEC tokens

To view a list of existing HEC tokens in your Splunk Cloud Platform environment, send an HTTP GET request to the following endpoint:

{stack}.splunkcloud.com:8089/services/dmc/config/inputs/-/http

For example:

curl -k -H "Authorization: Bearer ${TOKEN}" \
"https://{stack}.splunkcloud.com:8089/services/dmc/config/inputs/-/http?output_mode=json"

The request returns token names, full token values, indexes, and enabled status. For example:

{"entry": [{"name": "hec-token-name", "content": {"host": "{stack}.splunkcloud.com", "token": "CA56FE9A-0F8E-4D77-B3C6-8D9AFA9AB36F", "indexes": "main", "index": "main", "disabled": "false"}, "acl": {"app": "__indexers", "@bundleType": "builtin", "@bundleId": "indexers"}, "@status": "deployed", "links": {"alternate": "/services/dmc/config/inputs/__indexers/http/hec-token-name", "list": "/services/dmc/config/inputs/__indexers/http/hec-token-name", "edit": "/services/dmc/config/inputs/__indexers/http/hec-token-name", "disable": "/services/dmc/config/inputs/__indexers/http/hec-token-name/disable", "delete": "/services/dmc/config/inputs/__indexers/http/hec-token-name"}}], "paging": {"perPage": 30, "offset": 0, "total": 1}, "links": {}}

Create new HEC token

To create a new HEC token, send an HTTP POST request to the following endpoint, specifying a unique HEC token name and the default index:

{stack}.splunkcloud.com:8089/services/dmc/config/inputs/__indexers/http

For example:

curl -X POST -k -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
"https://{stack-name}.splunkcloud.com:8089/services/dmc/config/inputs/__indexers/http" \
--data-raw '{"name":"hec-token-name","index":"main","indexes":"main"}'

The request output includes the full token value. For example:

{"entry": [{"name": "hec-token-name", "content": {"disabled": "false", "indexes": "main", "token": "B2085AAA-5213-4581-9F63-29BB9BCBC121", "index": "main"},

[...]

} 

View individual HEC token

To view an individual HEC token, send an HTTP GET request to the following endpoint, specifying the name of the token:

{stack}.splunkcloud.com:8089/services/dmc/config/inputs/__indexers/http/{hec-token-name}

For example:

curl -k -H "Authorization: Bearer ${TOKEN}" \
"https://{stack-name}.splunkcloud.com:8089/services/dmc/config/inputs/__indexers/http/{hec-token-name}?output_mode=json"

The request returns details of the individual HEC token, including the full token value, index, and enabled status. For example:

{"entry": [{"name": "hec-token-name", "content": {"disabled": "false", "indexes": "main", "token": "B2085AAA-5213-4581-9F63-29BB9BCBC121", "index": "main"},
 
[...]

}

Delete an HEC token

To delete an individual HEC token, send an HTTP DELETE request to the inputs/__indexers/http/{hec-token-name} endpoint, specifying the name of the HEC token you want to delete. For example:

curl -k -H "Authorization: Bearer ${TOKEN}" -X 'DELETE' "https://{stack-name}.splunkcloud.com:8089/services/dmc/config/inputs/__indexers/http/{hec-token-name}"