Manage encrypted tokens using the REST API

Splunk MCP Server provides REST API endpoints for creating and managing encrypted MCP tokens. You can use the REST API to automate token-management tasks, including creating, listing, enabling, disabling, and deleting tokens.

Administrators can also use the REST API to manage the encryption key used for MCP encrypted tokens.

The REST API follows the same authorization requirements, token limits, and management rules as the Splunk MCP Server app. For information about managing encrypted tokens through the app, see Manage encrypted tokens for Splunk MCP Server.

Before you begin

You must authenticate REST API requests using a Splunk username and password or a Splunk authentication token.

The following capabilities are required for token-management operations:

Operation

Required capabilities

Manage your own encrypted MCP tokens mcp_edit_tokens_own and edit_tokens_own
Manage tokens and encryption keys as an administrator mcp_edit_tokens_own and mcp_tool_admin
Create, delete, and manage tokens for another user mcp_edit_tokens_own, mcp_tool_admin, and edit_tokens_all

REST API endpoint

Use the following base URL for encrypted MCP token-management operations:

https://<splunk_host>:8089/services/mcp_token

Replace <splunk_host> with the hostname of your Splunk deployment. Append the appropriate request path from the following table to the base URL to form the complete endpoint.

The following REST API operations are available.

Operation Request Access
List your tokens GET /tokens Self-service user
List all tokens GET /tokens?scope=all Administrator
Create a token POST /tokens Self-service user or administrator
Enable or disable a token PUT /tokens/{token_id} Token owner or administrator
Delete a token DELETE /tokens/{token_id} Token owner or administrator
View encryption-key status GET /key-pair Administrator
Create an encryption key POST /key-pair Administrator
Delete an encryption key DELETE /key-pair Administrator

Append the request path shown in the table to the base URL to form the complete endpoint for each operation.

Request parameters

The following table describes the request parameters identified for encrypted MCP token and encryption-key operations. The available parameters depend on the operation being performed.

Operation Parameter Description
List all tokens scope=all Lists tokens across users. Administrator only.
Filter listed tokens username Filters by username.
Filter listed tokens creator Filters by token creator.
Filter listed tokens admin_created Filters by whether a token was administrator-created.
Filter listed tokens state Filters by token state.
Create a token name Name of the token.
Create a token expires_on Requested token expiration.
Create a token not_before Requested start of token validity.
Create a token username User for whom the token is created. Administrator only.
Enable or disable a token disabled Set to true to disable a token or false to enable it.
Create an encryption key key_size Optional encryption-key size.
Create an encryption key valid_until Optional encryption-key expiration date, no more than 365 days after the creation date.

Examples

The following examples demonstrate how to create and delete encrypted MCP tokens using the REST API.

Create an encrypted token for yourself:

JSON
# Create your own token that expires in 30 days
curl -X POST "https://<splunk_host>:8089/services/mcp_token/tokens?output_mode=json" \
  -H "Authorization: Bearer <splunk_auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-laptop", "expires_on": "+30d"}'

Create an encrypted token for another user:

JSON
# Admin: create a token for user alice
curl -X POST "https://<splunk_host>:8089/services/mcp_token/tokens?output_mode=json" \
  -H "Authorization: Bearer <splunk_auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "alice-cursor", "username": "alice", "expires_on": "+30d"}'

Delete an encrypted token:

CODE
# Delete a token
curl -X DELETE "https://<splunk_host>:8089/services/mcp_token/tokens/<token_id>?output_mode=json" \
  -H "Authorization: Bearer <splunk_auth_token>"

Response behavior and errors

When you create an encrypted MCP token, the API returns the encrypted token value once. If the encryption key expires before the requested token expiration date, the token expiration is shortened accordingly.

The following table lists common HTTP error codes for encrypted MCP token-management operations:

HTTP status Description
400 The request is invalid.
401 The request is not authenticated.
403 The user does not have permission to perform the operation.
404 The requested resource was not found.
405 The method is not allowed.
409 An encryption key already exists when attempting to create another key.
412 The precondition failed.
429 Too many requests.
500 Internal server error.

Considerations when upgrading to version 2.1 or higher

When upgrading Splunk MCP Server from a version lower than 2.1 to version 2.1 or higher, review the following changes to encrypted token and encryption-key management:

  • Update token-creation scripts. If you use scripts to create encrypted MCP tokens, update them to use the POST method instead of GET.

  • Review existing encryption keys. Encryption keys created in versions lower than 2.1 without an expiration date remain valid for 180 days after upgrading to version 2.1 or higher. After that period, the keys become invalid.

  • Review tokens before deleting encryption keys. There is no grace period for encryption-key deletion. Deleting an encryption key immediately invalidates the associated tokens. Before deleting a key, verify that its associated tokens are disabled and no longer in use.

  • Create new encryption keys. Administrators should create new encryption keys to allow non-administrator users to create their own encrypted MCP tokens.

Replace encrypted tokens in automated workflows

To replace an encrypted MCP token in an automated workflow, complete the following steps:

  1. Create a new encrypted MCP token using the REST API.

  2. Update the MCP client or automated workflow to use the new token.

  3. Delete the old token after confirming that the updated workflow operates successfully.