Splunk Cloud Platform

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

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

To manage HEC tokens using the ACS API, you must:

  • Have the sc_admin (Splunk Cloud Platform Administrator) role.
  • Have Splunk Cloud Platform version 8.1.2101 or higher.

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

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.

Determine the correct REST API for your Splunk 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 on Victoria Experience only. If your Splunk Cloud Platform deployment is on Classic Experience, you can alternatively 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.

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-095f9f22699dbc279.myname.splunkcloud.com",
               "defaultIndex": "main",
               "defaultSource": "",
               "defaultSourcetype": "",
               "disabled": true,
               "name": "hec-token-name",
               "useACK": true
           },
           "token": "9803a48f-b733-4106-8a3f-871c53ee2675"
       }
   ]
}

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 specify a token value in the request body to use an existing HEC token.

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-095f9f22699dbc279.myname.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-0ebaaf05b6ca00907.myname.splunkcloud.com",
      "defaultIndex": "final_test_1",
      "defaultSource": "",
      "defaultSourcetype": "",
      "disabled": false,
      "name": "testhec",
      "useAck": false
    },
    "token": "a8d0472c-aa9e-4f35-aadb-8a35cae7c8e2"
  }
}

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. You cannot update the token value itself. 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/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 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-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}"
Last modified on 08 June, 2022
PREVIOUS
Manage authentication tokens in Splunk Cloud Platform
  NEXT
Manage indexes in Splunk Cloud Platform

This documentation applies to the following versions of Splunk Cloud Platform: 8.2.2109, 8.2.2111, 8.2.2112, 8.2.2201 (latest FedRAMP release), 8.2.2202, 8.2.2203


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