Splunk Cloud Platform

Admin Config Service Manual

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Basic setup and usage concepts for the Admin Config Service (ACS) API

This page discusses basic setup steps and usage concepts for the ACS API.

Set up the ACS API

To set up the ACS API, follow these steps:

  1. Retrieve the ACS Open API 3.0 specification.
  2. Create an authentication token.
  3. (optional) Set up an API client.

Retrieve the ACS OpenAPI 3.0 specification

ACS provides an OpenAPI 3.0 specification that includes all parameters, response codes, and other meta data that you need to send requests to the ACS API endpoint.

To retrieve the ACS OpenAPI 3.0 specification, send an HTTP GET request to:

https://admin.splunk.com/service/info/specs/v2/openapi.json

The ACS OpenAPI 3.0 specification includes a Splunk legal disclaimer for private app installation. When using the ACS API to install private apps, you must specify the ACS-Legal-Ack: Y parameter to acknowledge your acceptance of the following:

I acknowledge that Splunk is not responsible for the installation or use of any application that is not a supported Splunk application and Splunk specifically disclaims the accuracy, integrity, quality, legality, usefulness or security of such application or its use. Installation and use of an application that is not a supported Splunk application is at your own risk. Please note that if data leaves Splunk Cloud Platform as a result of installing or using such application, Splunk's security attestations do not apply to data outside Splunk Cloud Platform.

For more information on installing private apps using the ACS API, see Manage private apps in Splunk Cloud Platform.

Create an authentication token

The ACS API uses authentication tokens, in the form of a JSON Web Token (JWT), to authenticate and authorize ACS endpoint requests. You can create this token manually in the Splunk Web UI or programmatically using the ACS API. You must provide the token with each ACS API request.

To create an authentication token in Splunk Web:

  1. In Splunk Web, click Settings > Token > Enable Token Authentication > New Token.
  2. Configure the new token. Set an expiration time that meets your organization's needs. An expiration time of 60d fits most use cases.
  3. Copy/paste your token into your API client or save for use in curl requests.

For instructions on how to create an authentication token programmatically using the ACS API, see Create a new authentication token.

For more information on authentication tokens, see Set up authentication with tokens in the Securing Splunk Cloud Platform manual.

Set up API client (optional)

When setting up an API client, such as Postman, specify the following parameters:

  • {baseURL}: admin.splunk.com
  • {stack}: The URL prefix of your Splunk Cloud Platform deployment (e.g. csms-2io6tw-47150)
  • {token}: The JWT authentication token you create in Splunk Cloud Platform. See Create an authentication token.
  • {feature}: (ACS IP allow lists only) The feature to which IP allow list requests apply. See Determine IP allowlist use case.

When using the curl command, you must specify the required parameters with each request.

ACS API basic concepts

The API conforms to the Representational State Transfer (REST) architectural style. This REST API implementation accesses domain resources with corresponding endpoints, using the HTTP protocol. Your browser uses the same protocol, so you can use it to send API requests to the server. The Uniform Resource Locator (URL) addressing defined as part of the HTTP protocol maps to Splunk platform resources identified by their Uniform Resource Identifier (URI).

For example, if your Splunk Cloud Platform deployment is on Victoria Experience, a request to the following URL returns a list of applications installed on your server:

https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria

Format API requests

When you use the ACS API, encrypt your requests by using the secure HTTPS protocol. You must also use URI encoding for pathnames in URIs and search parameters. See the following example of a correctly formatted URI:

https://admin.splunk.com/{stack}/services/data/inputs/monitor/%2Fvar%2Flog

Every URI must include the base URL and stack. The base URL is admin.splunk.com, and the stack is the URL prefix of your Splunk Cloud Platform deployment (e.g. csms-2io6tw-47150).

Supported HTTP methods

The ACS API exposes the following REST methods subset. See the Admin Config Service API endpoint reference for which endpoints support which methods. Each method corresponds to a CRUD operation.

Method Operation Description
GET Read If the endpoint represents a collection, list the members of the collection. Iterate over the resource hierarchy to see the instantiated endpoints. Otherwise, the endpoint is a terminal node in the resource hierarchy and the GET request gets the current resource state as a list of property key-value pairs.
PATCH Update Use the PATCH method to update existing resource data.
POST Create Use the POST method to create a resource.
PUT Update Use the PUT method to create a resource or update existing resource data.
DELETE Delete Use the DELETE method to delete an endpoint from the resource hierarchy.

All methods return a HTTP status code to indicate the success of the operation or cause of a failure to fulfill the request.

HTTP Status Codes

Responses can include one of the following HTTP status codes in addition to content data. A complete list of status codes are not part of endpoint descriptions because the implementation follows the HTTP standard for reporting status. Status codes with special significance for the endpoint, or whose Splunk software specific cause differs from the standard, are noted in the ASC API endpoint reference.

See the Hypertext Transfer Protocol -- HTTP/1.1, Status Code Definitions standard for the complete list of status codes and their meaning.

Status code Description
200 Request completed successfully.
201 Create request completed successfully.
202 Request accepted for processing, but processing has not completed.
400 Request error. See response body for details.
401 Authentication failure, invalid access credentials.
402 In-use Splunk software license disables this feature.
403 Insufficient permission.
404 Requested endpoint does not exist.
409 Object already exists.
500 Unspecified internal server error. See response body for details.
503 Service Temporarily Unavailable, Please Try again.

For more information on ACS status codes, see Troubleshoot ACS error messages.

Last modified on 22 November, 2023
PREVIOUS
Admin Config Service (ACS) requirements and compatibility matrix
  NEXT
Target a specific search head for ACS operations

This documentation applies to the following versions of Splunk Cloud Platform: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308 (latest FedRAMP release), 9.1.2312


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