HTTP Event Collector token management

HTTP Event Collector uses tokens to authenticate the event data that it receives. If the token in the authorization header of a given request doesn't match one of its allowed tokens, HTTP Event Collector doesn't allow Splunk Enterprise or Splunk Cloud to consume the data.

HTTP Event Collector tokens are globally unique identifiers (GUIDs) that the Event Collector generates. The token administrator (which may also be the Splunk administrator) gives the token to the sender of the data (for example, the app developer) to be included in the authorization header. By using a token instead of Splunk Enterprise or Splunk Cloud credentials, you avoid the potential security complications involved with sending credentials over the network and storing credentials in client apps.

There are several ways to create, delete, edit, and enable or disable an HTTP Event Collector token:

  • Use the Splunk Enterprise or Splunk Cloud UI
  • Use the command line interface (CLI)
  • Use cURL commands using the token management endpoint
  • Edit .conf files
Note: To manage HEC tokens in managed Splunk Cloud, you must open a request ticket with Splunk Support.

Use the Splunk Enterprise or Splunk Cloud UI

For those who are more comfortable using a user interface to administer Splunk Enterprise or self-service Splunk Cloud operations, all token operations are available through the UI. (Managed Splunk Cloud users must open a support ticket to perform token operations.)

  • Create a token using the UI
  • Edit a token using the UI
  • Enable or disable a token using the UI
  • Delete a token using the UI

Create an HTTP Event Collector token using the UI

To create a token using the Splunk Enterprise or Splunk Cloud UI:

  1. From the Settings menu, click Data inputs.

  2. On the Data inputs page, under Local inputs, click HTTP Event Collector.

  3. Click New Token.

  4. On the Select Source page:

    1. In the Name field, enter a descriptive, memorable name for the token.

    2. (Optional.) In the Source name override field, enter a sourcetype that you want Splunk Enterprise or Splunk Cloud to assign to events that are sent using this token.

    3. (Optional.) In the Description field, enter a description for the token. For example, you might want to enter a phrase that describes the kind of data that will be sent to Splunk Enterprise or Splunk Cloud using this token.

    4. (Optional.) From the Output Group popup menu, choose an existing forwarder output group. You define output groups in the outputs.conf file. For more information, see "Output group-related settings" in Configure HTTP Event Collector using .conf files, plus Configure forwarders with outputs.conf. You can also set up forwarding in Splunk Web. This generates a default output group called default-autolb-group.

    5. When you're done, click Next.

  5. On the Input Settings page:

    1. Under Sourcetype, choose what default sourcetype to be assigned to data that is received using this token. Choose Automatic to have the sourcetype assigned automatically. Choose Select to choose from a popup list of existing sourcetypes. Choose New to create a new sourcetype to assign to the data.

    2. Under Index, choose the indexes you want to allow data using this token to be stored in. When a developer configures the sender of the data, he or she can specify an index to store data. As long as the index the developer specifies appears in this list under Selected item(s), the data will be consumed. If it doesn't, the data will be thrown out. Move and create indexes as you want. From the Default index popup menu, choose the index to assign to data that does not already have an index specified.

    3. When you're done, click Review.

  6. On the Review page, review your settings—clicking the < button and making changes where necessary—and then click Submit.

Once you've created a new token, it will be listed on the HTTP Event Collector data input page. Go to Settings > Data inputs > HTTP Event Collector to see a list of the tokens.

Enable or disable an HTTP Event Collector token using the UI

You can enable or disable an HTTP Event Collector token. If a token is disabled, events sent with that token will not be accepted and the sending user will receive an error message. Changing the status of one Event Collector token does not change the status of other tokens.

To toggle the active status of an EC token:

  1. From the Settings menu, click Data inputs.

  2. On the Data inputs page, under Local inputs, click HTTP Event Collector.

  3. From the token list, locate the token whose status you want to toggle.

  4. In the Actions column for that token, click Disable or Enable. The token's status toggles immediately and the link changes to Enable or Disable based on the changed token status.

To disable all tokens, disable HTTP Event Collector:

  1. From the Settings menu, click Data inputs.

  2. On the Data inputs page, under Local inputs, click HTTP Event Collector.

  3. Click Global Settings.

  4. Next to All Token Inputs, click Disabled.

  5. Click Save. Though all tokens will still be visible in the list, they (and the feature itself) have all been disabled.

Delete an HTTP Event Collector token using the UI

You can delete a token if you don't plan to use it anymore. Deleting a token does not affect other tokens. Deleting all tokens does not disable HTTP Event Collector. You cannot undo this action. Clients that use a deleted token to send data to Splunk Enterprise can no longer authenticate with the token. You must generate a new token and change the client's configuration to send data again.

To delete an HTTP Event Collector token using the Splunk Enterprise or Splunk Cloud UI:

  1. From the Settings menu, click Data inputs.

  2. On the Data inputs page, under Local inputs, click HTTP Event Collector.

  3. From the token list, locate the token you want to delete.

  4. In the Actions column for that token, click Delete.

  5. If you're sure you want to delete the token, click Delete.

Edit an HTTP Event Collector token using the UI

You can edit any token settings (except the token's name and its value) after you've created the token.

To edit an HTTP Event Collector token using the Splunk Enterprise or Splunk Cloud UI:

  1. From the Settings menu, click Data inputs.

  2. On the Data inputs page, under Local inputs, click HTTP Event Collector.

  3. From the token list, locate the token you want to edit.

  4. In the Actions column for that token, click Edit.

  5. In the Edit Input pane, change any of the token's properties that you want. For a description of each setting, see Create an HTTP Event Collector token using the UI.

  6. When you're done, click Save.


Using the CLI

All HTTP Event Collector token operations are available via the command line interface (CLI). If you're unfamiliar with the CLI and how to access it, see About the CLI. You will need to have CLI access as described in the About the CLI topic before proceeding.

This section provides an introduction to using the CLI to interact with tokens. For a full list of supported HTTP Event Collector CLI commands, see "Supported CLI commands" in the Use the CLI to administer HTTP Event Collector topic. For a full list of supported parameters, see "Supported CLI parameters" in Use the CLI to administer HTTP Event Collector.

  • List the existing tokens using the CLI
  • Create a token using the CLI
  • Edit a token using the CLI
  • Enable or disable a token using the CLI
  • Enable or disable HTTP Event Collector using the CLI
  • Delete a token using the CLI

List the existing HTTP Event Collector tokens using the CLI

To list the existing tokens using the CLI, use the list command. For example, the following example CLI command lists the tokens that exist on the Splunk server at https://localhost:8089:

splunk http-event-collector list -uri "https://localhost:8089"

Create an HTTP Event Collector token using the CLI

To create a token using the CLI, use the create command. For example, the following example CLI command creates a token called "new-token," gives it a description (in quotation marks), and indicates HTTP Event Collector data should be saved to the "log" index on the Splunk server at https://localhost:8089:

splunk http-event-collector create new-token "this is a new token" -index log -uri "https://localhost:8089"

For a full list and descriptions of all supported CLI parameters, see Use the CLI to administer HTTP Event Collector.

Edit an HTTP Event Collector token using the CLI

You can update any token property (except a token's name or value) by using the CLI update command. For example, the following example CLI command updates the default index of the "my-token" token on the Splunk server at https://localhost:8089 to be "my-index:"

splunk http-event-collector update my-token -index my-index -uri "https://localhost:8089"

For a full list of all the parameters that can be updated using the CLI, see "Supported CLI parameters" in the Use the CLI to administer HTTP Event Collector topic.

Enable or disable an HTTP Event Collector token using the CLI

You can enable or disable a token using the CLI. Changing the status of one token does not change the status of other tokens. To enable or disable a token, use the enable or disable command, respectively. For example, the following example disables the token called "my-token2" on the Splunk server at https://localhost:8089:

splunk http-event-collector disable my-token2 -uri "https://localhost:8089"

Similarly, the following example enables the token called "my-token2" on the Splunk server at https://localhost:8089:

splunk http-event-collector enable my-token2 -uri "https://localhost:8089"

Enable or disable HTTP Event Collector using the CLI

You can enable or disable HTTP Event Collector itself by making a bulk change to all tokens using the CLI. Simply leave out a token name when using enable or disable. For example, the following disables HTTP Event Collector on the Splunk server with the address https://localhost:8089:

splunk http-event-collector disable -uri https://localhost:8089

Delete an HTTP Event Collector token using the CLI

To delete a token using the CLI, use the delete command and the token name. For example, the following example CLI command deletes the token called "old-token" from the Splunk server at https://localhost:8089:

splunk http-event-collector delete old-token -uri "https://localhost:8089"

Use cURL via the token management endpoint

All HTTP Event Collector token operations are available via the token management endpoint using cURL. The tokens are stored at the following REST API endpoint, assuming your Splunk server management address is https://localhost:8089:

https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/
  • List the existing HTTP Event Collector tokens using cURL
  • Create an HTTP Event Collector token using cURL
  • Edit an HTTP Event Collector token using cURL
  • Enable or disable an HTTP Event Collector token using cURL
  • Enable or disable HTTP Event Collector using cURL
  • Delete an HTTP Event Collector token using cURL

List the existing HTTP Event Collector tokens using cURL

You can list the existing tokens using cURL. For example, the following example cURL command lists the tokens that exist on the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http

Create an HTTP Event Collector token using cURL

To create a token using cURL, use the name property. For example, the following example CLI command creates a token called "mytoken," on the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http -d name=mytoken 

Edit an HTTP Event Collector token using cURL

You can update any token property (except its name or value) using cURL. For example, the following example cURL command updates the description of the "mytoken" token on the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken -d description=abc 

 You can update any of the following parameters:

Parameter Description
disabled Whether to disable the token. 1 indicates true; 0 indicates false.
description A description of the token.
indexes A list of indexes accepted by the token.
index The token's default index. Splunk Enterprise assigns this value to data that doesn't already have an index value set.
source The token's default source value. Splunk Enterprise assigns this value to data that doesn't already have a source value set.
sourcetype The token's default sourcetype value. Splunk Enterprise assigns this value to data that doesn't already have a sourcetype value set.
outoputgroup The token's default outputgroup value. An output group is a group of indexers set up by the Splunk software administrator to index the data. Splunk Enterprise assigns this value to data that doesn't already have an outputgroup value set.
port The HTTP Event Collector server port. The default value is 8088, but you can change it using this parameter.
enableSSL Whether the HTTP Event Collector server's protocol is HTTP or HTTPS. 1 indicates HTTPS; 0 indicates HTTP.
dedicatedIoThreads The number of dispatcher threads on the HTTP Event Collector server. The default value is 2. This setting should not be altered unless you have been requested to do so by Splunk Support. The value of this parameter should never be more than the number of physical CPU cores on your Splunk Enterprise server.

Enable or disable an HTTP Event Collector token using cURL

You can enable or disable a token using cURL. Changing the status of one token does not change the status of other tokens. To enable or disable a token, use the POST command, the token name, and the enable or disable endpoint, respectively. For example, the following example disables the token called "mytoken" on the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -X "POST" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken/disable

Similarly, the following example enables the token called "mytoken" on the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -X "POST" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken/enable

Enable or disable HTTP Event Collector using cURL

You can enable or disable HTTP Event Collector itself by making a bulk change to all tokens using cURL. Simply leave out a token name when using the enable or disable endpoint. To enable or disable HTTP Event Collector, use the POST command and the enable or disable endpoint, respectively. For example, the following example disables HTTP Event Collector on the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -X "POST" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/http/disable

Delete an HTTP Event Collector token using cURL

To delete a token using cURL, use the DELETE command and the token name. For example, the following example cURL command deletes the token called "mytoken" from the Splunk server at https://localhost:8089 via the user "admin:"

curl -k -X "DELETE" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken

Edit .conf files

Token settings are stored in the inputs.conf and outputs.conf files. For more information about editing these files, see Configure HTTP Event Collector using .conf files.