Manage authentication tokens in Splunk Cloud Platform

The ACS API requires a JSON Web Token (JWT) to authenticate ACS endpoint requests. You can use the ACS API itself to create these authentication tokens, which facilitates automated workflows that integrate ACS API requests. For example, you can set up a fully automated CI/CD pipeline for private app installation that includes the creation of the required token.

Requirements

To manage authentication tokens 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.0.2007 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.
• You must provide a valid username and password for basic authentication.

The ACS API does not support authentication token management on FedRAMP deployments.

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 an authentication token for use with ACS endpoint requests. You can create this token using the Splunk Web UI or using the ACS API itself. For details on how to set up the ACS API, see Set up the ACS API.

Manage authentication tokens using the ACS API

You can use the ACS API to view existing tokens, create new tokens, view individual tokens, and delete tokens.

Authentication tokens are valid only on the search head on which you create them. ACS does not replicate tokens across the search tier. By default ACS token operations apply to the first standard search head (sh1) or search head cluster (shc1) of your Splunk Cloud Platform deployment.

To create and manage tokens on additional search heads or premium search heads, you must target the specific search head on which you want to perform the ACS token operation. For more information, see Target a specific search head for ACS operations.

View existing authentication tokens

To list existing JWT authentication tokens in your environment, send an HTTP GET request to the following endpoint:

admin.splunk.com/{stack}/adminconfig/v2/tokens

For example:

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

The request returns information about each token, including token id, user, audience, status, and expiration date. For example:

[
     {
          "id": "d9637736177efc773ec8c5c04efcc2e19859cd852af00689ef81bf9e809364a8",
          "user": "admin",
          "audience": "acs-test",
          "status": "enabled",
          "expiresOn": "2021-11-19T00:34:46Z",
          "notBefore": "2021-10-20T00:34:46Z",
          "lastUsed": "2021-10-20T03:52:53Z",
          "lastUsedIP": "50.216.96.2"
     },
     {
          "id": "a9637736177efc773ec8c5c04efcc2e19859cd852af00689ef81bf9e80936984",
          "user": "admin",
          "audience": "acs-test2",
          "status": "enabled",
          "expiresOn": "2022-05-19T00:34:46Z",
          "notBefore": "2022-04-20T00:34:46Z",
          "lastUsed": "2022-04-24T03:52:53Z",
          "lastUsedIP": "45.216.96.2"
     }
]

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

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

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

Create a new authentication token

To create a new JWT authentication token, send an HTTP POST request to the tokens endpoint.

You must provide the username and password of your Splunk Cloud Platform deployment with the POST request to enable token authentication. You can do so by specifying your credentials in the request URL. You must also specify the user and audience parameters in the request body.

You can optionally specify the expiresOn parameter in either relative time (+<number>[s][m][h][d]) or absolute time (YYYY-MM-DDTHH:MM:SS[+HH:MM]). If you do not specify expiresOn in your request, ACS assigns a default value of 30 days.

For example:

curl -u username:password -X POST 'https://admin.splunk.com/keziabutterfinger/adminconfig/v2/tokens' \
--header 'Content-Type: application/json' \
--data-raw '{
  "user" : "admin",
  "audience" : "acs-test",
  "expiresOn" : "+100d"
}'

The request output shows the token ID and the full token value, as shown:

{
   "user": "admin",
   "audience": "acs-test",
   "id": "0c1daac93fd01bc50cfe8ed938ce401bc168a8730c1c9e2f343671541e759fbf",
   "token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...",
   "status": "enabled",
   "expiresOn": "2021-12-16T21:37:11Z",
   "notBefore": "2021-11-16T21:37:11Z"

You can optionally specify username:password as a b64 encoded string using a basic authentication header. For example: --header 'Authorization: Basic a2V6aWE6a2V6aWF0ZXN0'.

If you do not specify password in the request URL, ACS prompts you for the password associated with the username. If you do not specify user or audience in the request body, ACS returns a 400 error. Possible error responses include:

{
    "code": "400-bad-request",
    "message": "expires_on argument is in an invalid format."
}
{
    "code": "400-bad-request",
    "message": "audience must be sent in the request body"
}
{
    "code": "400-bad-request",
    "message": "user must be sent in the request body"
}
{
   "code": "401-unauthorized",
   "message": "call not properly authenticated"
}

ACS returns the token value once only in the initial POST request that creates the token. Subsequent GET requests to view individual tokens do not return the token value. Make sure to save the token in a secure location.

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

Create an ephemeral authentication token

The ACS tokens endpoint supports an optional type request parameter, which lets you create an ephemeral JWT token that expires by default after 6 hours. Ephemeral tokens are ideal for use cases in which you do not want to maintain long-lived credentials, such as initiating an automated CI/CD pipeline, or when working with contractors or third-parties that need only temporary access to a deployment.

You can specify a type value of either "static" or "ephemeral". If not specified, the type value defaults to "static".

While ephemeral tokens have a default expiration of 6 hours, you can use the expiresOn parameter to specify a value of less than 6 hours for the ephemeral token, but not greater than 6 hours.

To create an ephemeral token using the ACS API, send an HTTP POST request to the tokens endpoint, specifying "ephemeral" as the type value in the request body. You must also specify user and audience parameter values in the request body, and provide the username and password of your Splunk Cloud Platform deployment in the request URL. For example:

curl -u username:password -X POST 'https://admin.splunk.com/<stack name>/adminconfig/v2/tokens' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4    "user": "blah",
5    "audience": "test",
6    "type": "ephemeral"
7}'

The request output shows the token ID and the full token value, along with the expiresOn value for the ephemeral token. For example:

{
    "id": "e4a4514f1cc8d3103393e9f9521d0b92fada2464d9f0be2dd6753f7488ffed02",
    "token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...",
    "expiresOn": "+6h"
}

You cannot list ephemeral tokens with a GET request or delete them. You can only create ephemeral tokens and use them until they automatically expire.

Specifying a type value is optional. There is no difference between specifying "type": "static" in the request body and specifying no type parameter at all.

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

View individual tokens

To describe an individual token, send an HTTP GET request to the tokens/{id} endpoint, specifying the token ID that you received when you created the token. For example:

curl 'https://admin.splunk.com/important-iguana-u5q/adminconfig/v2/tokens/55ee3d1c199645c330d28dcd9fa50bc6e9f74154c3d1c3d31229b6e78be77ed7' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi…'

The authorization token that you use for the request does not have to be the token associated with the {id}.

The request returns token details, including time shown in UTC for the expiresOn, notBefore, and lastUsed parameters. For example:

{
   "id": "d9637736177efc773ec8c5c04efcc2e19859cd852af00689ef81bf9e809364a8",
   "user": "admin",
   "audience": "acs-test",
   "status": "enabled",
   "expiresOn": "2021-11-19T00:34:46Z",
   "notBefore": "2021-10-20T00:34:46Z",
   "lastUsed": "2021-10-20T03:52:53Z",
   "lastUsedIP": "50.216.96.2"
}

For endpoint details, see tokens/{id} in the ACS endpoint reference.

Delete token

To delete a token, send an HTTP DELETE request to the tokens/{id} endpoint, specifying the token ID of the token you want to delete. For example:

curl -X DELETE 'https://admin.splunk.com/important-iguana-u5q/adminconfig/v2/tokens/55ee3d1c199645c330d28dcd9fa50bc6e9f74154c3d1c3d31229b6e78be77ed7' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...'

The authorization token that you use for the request does not have to be the token associated with the {id}.

For endpoint details, see tokens/{id} in the ACS endpoint reference.