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.

For instructions on how to create a JWT authentication token in Splunk Web, see Use Splunk Web to create authentication tokens in Securing Splunk Cloud Platform.

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

Make sure to save your token in a secure location and share it only with those you have authorized to use it.

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

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.