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:
- Retrieve the ACS Open API 3.0 specification.
- Create an authentication token.
- (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.
Admin Config Service (ACS) requirements and compatibility matrix | 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, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!