Manage Splunkbase apps in Splunk Cloud Platform

The Admin Config Service (ACS) API supports programmatic self-service management of public apps available on Splunkbase. You can use the ACS API to install, list, describe, upgrade, and uninstall Splunkbase apps on your Splunk Cloud Platform deployment, without assistance from Splunk Support.

Requirements

To manage Splunkbase apps 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.2.2112 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.

If you plan to integrate ACS app management into your CI/CD pipeline, make sure to store your Splunk credentials (username and password) securely. To do so, you can integrate a solution such as Vault, which uses token authentication to protect your confidential data. See https://docs.gitlab.com/ee/ci/secrets in GitLab CI/CD documentation.

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

Determine the correct ACS API endpoints for your Splunk Cloud Platform Experience

The correct ACS API endpoints to use for Splunkbase app management depends on your Splunk Cloud Platform Experience. To find out if your deployment is on Classic Experience or Victoria Experience: In Splunk Web, click Support & Services > About.

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

• Manage Splunkbase apps using the ACS API on Victoria Experience
• Manage Splunkbase apps using the ACS API on Classic Experience

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

Manage Splunkbase apps using the ACS API on Victoria Experience

This section shows you how to install and manage Splunkbase apps using the ACS API on Splunk Cloud Platform deployments on Victoria Experience.

Retrieve Splunkbase session ID

Before you can install a Splunkbase app using the ACS API, you must retrieve a Splunkbase session ID. You must provide your Splunkbase session ID for authentication purposes when installing or upgrading Splunkbase apps using ACS.

To retrieve your Splunkbase session ID, send an HTTP POST request to the splunkbase.splunk.com/api/account:login endpoint, specifying your splunk.com username and password. For example:

curl -X POST 'https://splunkbase.splunk.com/api/account:login' \
--form 'username=myname@splunk.com' \
--form 'password=mypassword'

The request output includes the Splunkbase session ID. For example:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
   <title>Authentication Token</title>
   <updated>2022-01-19T19:20:07.079278+00:00</updated>
   <id>bgf4ztyxcgssgcbdrhguzl0xgousxzcq</id>
</feed>

Install a Splunkbase app on Victoria Experience

To install a Splunkbase app on Victoria Experience, send an HTTP POST request to the apps/victoria endpoint, specifying the splunkbase=true parameter in the request to indicate that the app you want to install is a Splunkbase app.

You must specify the SplunkbaseID of the app in the request body. You can find the SplunkbaseID in the URL of the Splunkbase app download page. For example, if the URL is https://splunkbase.splunk.com/app/491/, the SplunkbaseID is 491.

You can optionally specify the version number for the app you want to install. If you do not specify a version number, ACS automatically installs the latest version of the app that is both cloud-compatible and self-service installable. If the app you want to install is not self-serviceable, you must contact Splunk Support to install the app.

You must provide your Splunkbase session ID in the X-Splunkbase-Authorization header, and you must provide your Splunk Cloud Platform JWT authentication token in the Authorization header.

You must also acknowledge the app's third-party license by providing the license URL in the ACS-Licensing-Ack header. The license URL is available under "Licensing" on the Splunkbase download page for the app.

For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria?splunkbase=true' \
--header 'X-Splunkbase-Authorization: bgf4ztyxcgssgcbdrhguzl0xgousxzcq' \
--header 'ACS-Licensing-Ack: http://opensource.org/licenses/ISC' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'splunkbaseID=491' \
--data-urlencode 'version=<version>'

The request output shows "status": "installed" when app installation successfully completes. If the request output shows "status": "processing", this means the app installation request was successful, but app installation is still in-progress due to the asynchronous app installation process. For example:

{
   "appID": "SplunkforPaloAltoNetworks",
   "label": "Palo Alto Networks App for Splunk",
   "name": "SplunkforPaloAltoNetworks",
   "splunkbaseID": "491",
   "status": "processing",
   "version": "7.0.4"
}

If you provide an invalid license URL for the Splunkbase app, ACS returns a 400 status message that includes the correct license URL. For example:

{
   "code": "400-bad-request",
   "message": "The ACS-Licensing-Ack value was not provided or is not valid. The app, and any related dependency that will be installed, may be provided by Splunk and/or a third party and your right to use these app(s) is in accordance with the applicable license(s) provided by Splunk and/or the third-party licensor. Splunk is not responsible for any third-party app and does not provide any warranty or support. If you have any questions, complaints or claims with respect to an app, please contact the applicable licensor directly whose contact information can be found on the Splunkbase download page. Palo Alto Networks App for Splunk is governed by the following license: ISC License. By setting ACS-Licensing-Ack header to http://opensource.org/licenses/ISC, I am indicating that I have read the terms and conditions of the license and Splunk Website Terms of Use URL: https://www.splunk.com/en_us/legal/terms/terms-of-use.html and agree to be bound by them."

For endpoint details, see apps/victoria in the ACS endpoint reference.

View installed Splunkbase apps on Victoria Experience

To view a list of Splunkbase apps currently installed on your deployment, send an HTTP GET request to the apps/victoria endpoint, specifying the splunkbase=true parameter in the request. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria?splunkbase=true' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

Optionally, to list all non-Splunkbase apps, specify splunkbase=false in the request. Or, to list all apps, including all Splunkbase and private apps, do not specify the splunkbase parameter.

The request output lists Splunkbase apps on your deployment. For example:

{
   "apps": [
       {
           "appID": "python_upgrade_readiness_app",
           "label": "Upgrade Readiness App",
           "name": "python_upgrade_readiness_app",
           "splunkbaseID": "5483",
           "status": "installed",
           "version": "3.0.0"
       },
       {
           "appID": "splunk_product_guidance",
           "label": "Splunk Product Guidance",
           "name": "splunk_product_guidance",
           "splunkbaseID": "5137",
           "status": "installed",
           "version": "1.2.1"
       }
   ]
}

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

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

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria?offset=100&count=100&splunkbase=true'

For endpoint details, see apps/victoria in the ACS endpoint reference.

Describe a Splunkbase app on Victoria Experience

To view details of an individual app, send an HTTP GET request to the apps/victoria/{app_name} endpoint, specifying the name of the app. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria/SplunkforPaloAltoNetworks' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

The request returns information about the specific app, including the app installation status. When app installation successfully completes, the request output shows "status": "installed". For example:

{
   "appID": "SplunkforPaloAltoNetworks",
   "label": "Palo Alto Networks",
   "name": "SplunkforPaloAltoNetworks",
   "splunkbaseID": "491",
   "status": "installed",
   "version": "7.0.4"
}

For endpoint details, see apps/victoria/{app_name} in the ACS endpoint reference.

Upgrade a Splunkbase app on Victoria Experience

To upgrade or downgrade a Splunkbase app, send an HTTP PATCH request to the apps/victoria/{app_name} endpoint, specifying the app name in the request URL and the app version in the request body. When upgrading to the latest version of an app, you do not need to specify the app version.

You must provide your Splunkbase session ID in the X-Splunkbase-Authorization header, and you must provide your Splunk Cloud Platform JWT authentication token in the Authorization header.

You must also acknowledge the app's third-party license by providing the license URL in the ACS-Licensing-Ack header. The license URL is available under "Licensing" on the Splunkbase download page for the app.

For example:

curl -X PATCH 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria/SplunkforPaloAltoNetworks' \
--header X-Splunkbase-Authorization: 'bgf4ztyxcgssgcbdrhguzl0xgousxzcq' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'ACS-Licensing-Ack: http://opensource.org/licenses/ISC' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…' \
--data-urlencode 'version=7.0.3'

The request output shows "status": "installed" when app updgrade successfully completes. If the request output shows "status": "processing", this means the app upgrade request was successful, but app upgrade is still in-progress due to the asynchronous app installation process. For example:

{
   "appID": "SplunkforPaloAltoNetworks",
   "label": "Palo Alto Networks App for Splunk",
   "name": "SplunkforPaloAltoNetworks",
   "splunkbaseID": "491",
   "status": "processing",
   "version": "7.0.3"
}

For endpoint details, see apps/victoria/{app_name} in the ACS endpoint reference.

Uninstall a Splunkbase app on Victoria Experience

To uninstall a Splunkbase app, send an HTTP DELETE request to the apps/victoria/{app_name} endpoint, specifying the name of the app. For example:

curl -X DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria/SplunkforPaloAltoNetworks' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...'

For endpoint details, see apps/victoria/{app_name} in the ACS endpoint reference.

Manage Splunkbase apps using the ACS API on Classic Experience

This section shows you how to install and manage Splunkbase apps using the ACS API on Splunk Cloud Platform deployments on Classic Experience.

Retrieve Splunkbase session ID

Before you can install a Splunkbase app using the ACS API, you must retrieve a Splunkbase session ID. You must provide your Splunkbase session ID for authentication purposes when installing or upgrading Splunkbase apps using ACS.

For instructions on how to retrieve your Splunkbase session ID, see Retrieve Splunkbase session ID.

Install a Splunkbase app on Classic Experience

To install a Splunkbase app on Classic Experiencve, send an HTTP POST request to the apps endpoint, specifying the splunkbase=true query parameter to indicate that the app you want to install is a Splunkbase app.

You must specify the SplunkbaseID of the app in the request body. You can find the SplunkbaseID in the URL of the Splunkbase app download page. For example, if the URL is https://splunkbase.splunk.com/app/491/, the SplunkbaseID is 491.

You can optionally specify the version number for the app you want to install. If you do not specify a version number, ACS automatically installs the latest version of the app that is both cloud-compatible and self-service installable. If the app you want to install is not self-serviceable, you must contact Splunk Support to install the app.

You must provide your Splunkbase session ID in the X-Splunkbase-Authorization header, and you must provide your Splunk Cloud Platform JWT authentication token in the Authorization header.

You must also acknowledge the app's third-party license by providing the license URL in the ACS-Licensing-Ack header. The license URL is available under "Licensing" on the Splunkbase download page for the app.

For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/apps?splunkbase=true' \
--header 'X-Splunkbase-Authorization: bgf4ztyxcgssgcbdrhguzl0xgousxzcq' \
--header 'ACS-Licensing-Ack: http://opensource.org/licenses/ISC' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'splunkbaseID=491' \
--data-urlencode 'version=<version>'

The request output shows "status": "installed" when app installation successfully completes. If the request output shows "status": "processing", this means the app installation request was successful, but app installation is still in-progress due to the asynchronous app installation process. For example:

{
   "appID": "SplunkforPaloAltoNetworks",
   "label": "Palo Alto Networks App for Splunk",
   "name": "SplunkforPaloAltoNetworks",
   "splunkbaseID": "491",
   "status": "processing",
   "version": "7.0.4"
}

If you provide an invalid license URL for the Splunkbase app, ACS returns a 400 status message that includes the correct license URL. For example:

{
   "code": "400-bad-request",
   "message": "The ACS-Licensing-Ack value was not provided or is not valid. The app, and any related dependency that will be installed, may be provided by Splunk and/or a third party and your right to use these app(s) is in accordance with the applicable license(s) provided by Splunk and/or the third-party licensor. Splunk is not responsible for any third-party app and does not provide any warranty or support. If you have any questions, complaints or claims with respect to an app, please contact the applicable licensor directly whose contact information can be found on the Splunkbase download page. Palo Alto Networks App for Splunk is governed by the following license: ISC License. By setting ACS-Licensing-Ack header to http://opensource.org/licenses/ISC, I am indicating that I have read the terms and conditions of the license and Splunk Website Terms of Use URL: https://www.splunk.com/en_us/legal/terms/terms-of-use.html and agree to be bound by them."

For endpoint details, see apps in the ACS endpoint reference.

View installed Splunkbase apps on Classic Experience

To view a list of Splunkbase apps currently installed on your deployment, send an HTTP GET request to the apps endpoint, specifying the splunkbase=true query parameter. By default, the request returns a maximum count of 30 apps. To change the count, you can specify a count value up to a maximum of 100. A count value of 0 lists all apps. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps?offset=0&count=0&splunkbase=true' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

The request output lists Splunkbase apps on your deployment. For example:

{
   "apps": [
       {
           "appID": "python_upgrade_readiness_app",
           "label": "Upgrade Readiness App",
           "name": "python_upgrade_readiness_app",
           "splunkbaseID": "5483",
           "status": "installed",
           "version": "3.0.0"
       },
       {
           "appID": "splunk_product_guidance",
           "label": "Splunk Product Guidance",
           "name": "splunk_product_guidance",
           "splunkbaseID": "5137",
           "status": "installed",
           "version": "1.2.1"
       }
   ]
}

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

For endpoint details, see apps in the ACS endpoint reference.

Describe a Splunkbase app on Classic Experience

To view details of an individual app, send an HTTP GET request to the apps/{app_name} endpoint, specifying the name of the app. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/SplunkforPaloAltoNetworks' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

The request returns information about the specific app, including the app installation status. When app installation successfully completes, the request output shows "status": "installed". For example:

{
   "appID": "SplunkforPaloAltoNetworks",
   "label": "Palo Alto Networks",
   "name": "SplunkforPaloAltoNetworks",
   "splunkbaseID": "491",
   "status": "installed",
   "version": "7.0.4"
}

For endpoint details, see apps/{app_name} in the ACS endpoint reference.

Upgrade a Splunkbase app on Classic Experience

To upgrade a Splunkbase app, send an HTTP PATCH request to the apps/{app_name} endpoint, specifying the Splunkbase app name in the request URL and the Splunkbase app ID in the request body.

You must provide your Splunkbase session ID in the X-Splunkbase-Authorization header. See Retrieve Splunkbase session ID.

You must also provide your Splunk Cloud Platform JWT authentication token in the Authorization header.

And you must acknowledge the app's third-party license by providing the license URL in the ACS-Licensing-Ack header. The license URL is available under "Licensing" on the Splunkbase download page for the app.

ACS supports upgrade to the latest version of a Splunkbase app only. ACS does not support downgrade to an earlier version of a Splunkbase app.

For example:

curl -X PATCH 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/SplunkforPaloAltoNetworks' \
--header X-Splunkbase-Authorization: bgf4ztyxcgssgcbdrhguzl0xgousxzcq' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'ACS-Licensing-Ack: http://opensource.org/licenses/ISC' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…' \
--data-urlencode 'splunkbaseID=491'

The request output shows "status": "installed" when app updgrade successfully completes. If the request output shows "status": "processing", this means the app upgrade request was successful, but app upgrade is still in-progress due to the asynchronous app installation process. For example:

{
   "appID": "SplunkforPaloAltoNetworks",
   "label": "Palo Alto Networks App for Splunk",
   "name": "SplunkforPaloAltoNetworks",
   "splunkbaseID": "491",
   "status": "processing",
   "version": "7.0.3"
}

For endpoint details, see apps/{app_name} in the ACS endpoint reference.

Uninstall a Splunkbase app on Classic Experience

To uninstall a Splunkbase app, send an HTTP DELETE request to the apps/{app_name} endpoint, specifying the name of the Splunkbase app. For example:

curl -X DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/SplunkforPaloAltoNetworks' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...'

For endpoint details, see apps/{app_name} in the ACS endpoint reference.

Customize a Splunkbase App for private app installation

If you want to customize a Splunkbase app and install the app as a private app on your Splunk Cloud Platform deployment, make sure the customized app meets the following conditions:

• The app must have a unique App ID. Change the App ID if necessary.
• The Splunkbase app itself must be cloud compatible and self-service installable.

For more information on apps, see Splunkbase and private apps in Splunk Cloud Platform Service Details.

For ACS private app installation instructions, see Manage private apps in Splunk Cloud Platform in the Admin Config Service Manual.

For additional information, see the following topics in the Splunk Cloud Platform Admin Manual:

• Install apps on your Splunk Cloud Platform deployment.
• Manage private apps on your Splunk Cloud Platform deployment.