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:
# 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:
# 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:
# 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:
-
Create a new encrypted MCP token using the REST API.
-
Update the MCP client or automated workflow to use the new token.
-
Delete the old token after confirming that the updated workflow operates successfully.