Splunk Cloud Platform

Splunk Cloud Platform Admin Manual

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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 Splunk Cloud Admin Config Service (ACS) API to create and manage HEC tokens programatically.

If your Splunk Cloud Platform deployment is in an AWS region, before you can use the ACS API, your account must be properly onboarded. For onboarding assistance, contact Splunk Support. If your Splunk Cloud Platform deployment is in a Google Cloud region, onboarding is not required.

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

Requirements

  • Splunk Cloud Platform version 8.0.2007 or higher is required to generate authentication tokens/
  • Splunk Cloud Platform version 8.1.2101 or higher is required for HEC support.
  • You must have the sc_admin role.
  • cURL or equivalent API client tool, such as POSTMAN.

The ACS API does not currently support AWS GovCloud or FedRAMP environments.

Determine the correct REST API for your Spunk Cloud Platform Experience

Each Splunk Cloud Platform deployment has an "Experience" designation: Victoria or Classic. The ACS API is available for HEC token management on Splunk Cloud Platform deployments running on the Victoria Experience only. Splunk Cloud Platform deployments running on the Classic Experience, can use Splunk Cloud Classic endpoints for HEC token management. To find your deployment's Experience, in Splunk Web, click Support & Services > About.

After you determine your deployment's Experience, follow the instructions that apply to your deployment:

For more information on the Splunk Cloud Platform Experience, see Determine your Splunk Cloud Platform Experience.

Manage HEC tokens using the ACS API

The following sections 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 the Victoria Experience only. For deployments on the Splunk Cloud Classic Experience, see Manage HEC tokens using Splunk Cloud Classic endpoints.

Set up the ACS API for HEC token management

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 generate an authentication token in Splunk Cloud Platform for use with ACS endpoint requests. For details on how to set up the ACS API for HEC token management, see Set up the ACS API.

View existing HEC tokens

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

{baseUrl}/{stack}/adminconfig/v1/inputs/http-event-collectors

For example:

curl https://admin.splunk.com/{stack}/adminconfig/v1/inputs/http-event-collectors

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

{
   "http-event-collectors": [
       {
           "spec": {
               "allowedIndexes": [
                   "main",
                   "summary"
               ],
               "defaultHost": "",
               "defaultIndex": "main",
               "defaultSource": "",
               "defaultSourcetype": "",
               "disabled": true,
               "name": "hec-token-name"
           },
           "token": "67b9dc80-redacted"
       }
   ]
}

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.

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/v1/inputs/http-event-collectors' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiw...' \
--header 'Content-Type: application/json' \
--data-raw '{
   "allowedIndexes": [
       "main",
       "summary"
   ],
   "defaultHost": "",
   "defaultIndex": "main",
   "defaultSource": "",
   "defaultSourcetype": "",
   "disabled": false,
   "name": "hec-token-name"
}'

The request output includes the full HEC token value, as shown:

"http-event-collector": {
       "spec": {
           "allowedIndexes": [
               "main",
               "summary"
           ],
           "defaultHost": "",
           "defaultIndex": "main",
           "defaultSource": "",
           "defaultSourcetype": "",
           "disabled": false,
           "name": "hec-token-name"
       },
       "token": "9803a48f-b733-4106-8a3f-871c53ee2675"
   }
}


A 200 response code indicates your request was submitted successfully. Note that the ACS request process is asynchronous and it can take several seconds to complete the token creation process. You can check the status of your request, as follows:

Send an HTTP GET request to the inputs/http-even-collectors/{hec-token-name} endpoint specifying the unique HEC token name, to confirm the creation of the new token. For example:

curl 'https://admin.splunk.com/wacky-walrus-f90/adminconfig/v1/inputs/http-event-collectors/hec-token-name'

Update an HEC token

To update an existing HEC token, send an HTTP PUT request to the inputs/http-event-collectors/{hec-token-name} endpoint, specifying the HEC token name and updated parameters. For example, the following request changes the disabled parameter to true, which disables the HEC token.

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

After the PUT request completes, you can 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 GET 'https://admin.splunk.com/wacky-walrus-f90/adminconfig/v1/inputs/http-event-collectors/hec-token-name'

Endpoint reference for HEC token management

inputs/http-event-collectors

https://admin.splunk.com/{stack}/adminconfig/v1/inputs/http-event-collectors

List and create HTTP Event Collector (HEC) tokens.


Authentication and Authorization
Requires a token (JWT) or local account.

GET

List existing HEC tokens.


Request parameters

Name Type Description
stack String The URL prefix of the Splunk Cloud Platform deployment.


Returned values

Name Type Description
name String The HEC token name. This is the token ID, not the actual token value.
disabled Boolean The enabled/disabled status of the HEC token.
defaultindex String Default index to store generated events.
token String The token value (redacted).

Example request and response

JSON Request

curl https://admin.splunk.com/{mystack}/adminconfig/v1/inputs/http-event-collectors

JSON Response

{
   "http-event-collectors": [
       {
           "spec": {
               "allowedIndexes": [
                   "main",
                   "summary"
               ],
               "defaultHost": "",
               "defaultIndex": "main",
               "defaultSource": "",
               "defaultSourcetype": "",
               "disabled": true,
               "name": "hec-token-name"
           },
           "token": "67b9dc80-redacted"
       }
   ]
}

POST

Create a new HEC token.


Request parameters

Name Type Description
stack String The URL prefix of the Splunk Cloud Platform deployment.
name String The HEC token name. This is the token ID, not the actual token value.
defaultIndex String Default index to store generated events.


Returned values

Name Type Description
token String The full token value.

Example request and response

JSON Request

curl -X POST 'https://admin.splunk.com/mystack/adminconfig/v1/inputs/http-event-collectors' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiw...' \
--header 'Content-Type: application/json' \
--data-raw '{
   "allowedIndexes": [
       "main",
       "summary"
   ],
   "defaultHost": "",
   "defaultIndex": "main",
   "defaultSource": "",
   "defaultSourcetype": "",
   "disabled": false,
   "name": "hec-token-name"
}'

JSON Response

"http-event-collector": {
       "spec": {
           "allowedIndexes": [
               "main",
               "summary"
           ],
           "defaultHost": "",
           "defaultIndex": "main",
           "defaultSource": "",
           "defaultSourcetype": "",
           "disabled": false,
           "name": "hec-token-name"
       },
       "token": "9803a48f-b733-4106-8a3f-871c53ee2675"
   }
}

inputs/http-event-collectors/{hec-token-name}

https://admin.splunk.com/{stack}/adminconfig/v1/inputs/http-event-collectors/{hec-token-name}

View, update, and delete HTTP Event Collector (HEC) tokens.


Authentication and Authorization
Requires a token (JWT) or local account.


GET

View an inidvidual HEC token.


Request parameters

Name Type Description
stack String The URL prefix of the Splunk Cloud Platform deployment.
name String The HEC token name. This is the token ID, not the actual token value.


Returned values

Name Type Description
disabled Boolean The enabled/disabled status of the HEC token.
defaultindex String Default index to store generated events.
token String The token value (redacted).

Example request and response

JSON Request

curl https://admin.splunk.com/{mystack}/adminconfig/v1/inputs/http-event-collectors/{hec-token-name}

JSON Response

{
   "http-event-collectors": [
       {
           "spec": {
               "allowedIndexes": [
                   "main",
                   "summary"
               ],
               "defaultHost": "",
               "defaultIndex": "main",
               "defaultSource": "",
               "defaultSourcetype": "",
               "disabled": true,
               "name": "hec-token-name"
           },
           "token": "67b9dc80-redacted"
       }
   ]
}

PUT

Update an existing HEC token.


Request parameters

Name Type Description
stack String The URL prefix of the Splunk Cloud Platform deployment.
defaultHost String Default index to store generated events.
defaultIndex String Default event source.
defaultSource String Default index to store generated events.
defaultSourcetype String Default index to store generated events.
disabled String Default index to store generated events.
name String The name of the HEC token. This is the token ID, not the actual token value.


Returned values
None

Example request and response

JSON Request

curl -X PUT 'https://admin.splunk.com/{mystack}/adminconfig/v1/inputs/http-event-collectors' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiw...' \
--header 'Content-Type: application/json' \
--data-raw '{
   "allowedIndexes": [
       "main",
       "summary"
   ],
   "defaultHost": "",
   "defaultIndex": "main",
   "defaultSource": "",
   "defaultSourcetype": "",
   "disabled": false,
   "name": "hec-token-name"
}'

JSON Response

{
"code": "200"
}

DELETE

Delete an HEC token.


Request parameters

Name Type Description
stack String The URL prefix of the Splunk Cloud Platform deployment.
name String The HEC token name. This is the token ID, not the actual token value.


Returned values
None


Example request and response

JSON Request

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

JSON Response

{
"code": "200"
}

Manage HEC tokens using Splunk Cloud Classic endpoints

The following examples show how you can use Splunk Cloud Classic endpoints to manage your HEC tokens.

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 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 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}"
Last modified on 07 September, 2021
PREVIOUS
Configure IP allow lists for Splunk Cloud Platform
  NEXT
Manage Splunk Cloud Platform users and roles

This documentation applies to the following versions of Splunk Cloud Platform: 8.1.2101, 8.1.2103, 8.2.2104, 8.2.2105 (latest FedRAMP release), 8.2.2106, 8.2.2107


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