TrackMe REST API
TrackMe provides a deep REST API that allows interracting with any of its components, in fact, all interactions from the user interfaces deal with TrackMe’s REST API endpoints.
Hint
Since the version 2.0.34, TrackMe implements a strict least privileges approach:
Endpoints are eventually (depending on the resource group) separated in 3 groups per resource groups, user level endpoints, write level endpoints and admin level endpoints
According to the RBAC configuration, a given user may not be granted access to write and admin endpoints if the user is a normal user, or the user may not be granted access to the admin endpoints if the user is power user
These are driven by TrackMe’s builtin Splunk capabilities which can be granted to a given Splunk role, by membership or inheritance (see: Role Based Access Control and ownership)
The following table summarizes TrackMe’s builtin roles, associates capabilities, endpoints accesses and privileges categories:
Role |
Capability |
Endpoints root |
Description |
---|---|---|---|
trackme_user |
trackmeuseroperations |
all but write and admin |
allows read only access in TrackMe |
trackme_power |
trackmepoweroperations |
*/write |
allows management of TrackMe entities but not the creation of new content (such as trackers) |
trackme_admin |
trackmeadminoperations |
*/admin |
allows content management such as the creation of tenants and trackers |
REST API reference
TrackMe comes with a REST API reference user interface which allows you to navigate through the available API endpoints categorized by resource groups:
Go to Navigation bar / API & Tooling / TrackMe REST API Reference:
![screen1.png](_images/screen126.png)
REST API resource groups
At the top level, TrackMe REST API endpoints are categorized by resource groups:
![screen2.png](_images/screen221.png)
TrackMe has a concept of automatic discovery of the REST API endpoints and their documentation, for this, we leverage a custom command:
| trackmeapiautodocs
![screen3.png](_images/screen39.png)
The custom command trackmeapiautodocs
automatically discovers REST API endpoints and extract their documentation such as the endpoint URI, the expected HTTP mode, options available for that endpoint and the example of use in SPL:
To list all resource groups, you can use the following SPL command:
| trackmeapiautodocs target="groups" | table resource_group, resource_desc | sort 0 resource_group
To retrieve the list of API endpoints and their detail, you can use the following SPL command:
Example:
| trackmeapiautodocs target="endpoints" | search resource_group="splk_hybrid_trackers"
![screen4.png](_images/screen48.png)
REST API logging access
Any activity of the REST API endpoints is carefully logged, consult REST API endpoints logging
REST API audit
Any endpoint performing a change in TrackMe, such as deleting an entity, leads to the generation of one or more audit events from that endpoint.
For instance, you can search for all audit events for a given Virtual Tenant:
index=trackme_audit tenant_id=mytenant
REST API usage example in Splunk
REST API endpoints can therefore be used programmatically for any kind of action, within Splunk using the trackme
REST API wrapper custom command, and externally using any program of your choice, from curl
to Postman
and others.
For instance, the usage for retrieving the details of existing Virtual Tenants:
| trackme url="/services/trackme/v2/vtenants/show_tenants" mode="get"
![screen5.png](_images/screen57.png)
This other example would create a brand new virgin Virtual Tenant for splk-dsm:
| trackme url="/services/trackme/v2/vtenants/admin/add_tenant" mode="post" body="{ 'tenant_desc': 'Demo tenant', 'tenant_name': 'mytenant', 'tenant_roles_admin': 'trackme_admin', 'tenant_roles_user': 'trackme_user', 'tenant_owner': 'admin', 'tenant_idx_settings': 'global', 'tenant_dsm_enabled': 'true', 'tenant_dsm_sampling_obfuscation': 'disabled', 'update_comment': 'Created for the purpose of the documentation.'}"
![screen6.png](_images/screen65.png)
The following example deletes that same Virtual Tenant we’ve created:
| trackme url=/services/trackme/v2/vtenants/admin/del_tenant mode=delete body="{ 'tenant_id': 'mytenant', 'force': 'true'}"
![screen7.png](_images/screen76.png)
Audit messages are generated and indexed in the Virtual Tenant audit index:
index=trackme_audit tenant_id=mytenant
![screen8.png](_images/screen85.png)
REST API usage example outside of Splunk
Authenticating to the Splunk API
Using a bearer token:
The best approach for using the Splunk REST API is to rely on a bearer token to authenticate and access to splunkd:
See: Splunk docs JSON authentication token
Once you have created an authentication token for the user to be used as the service account, using curl specify the bearer token:
curl -k –H "Authorization: Bearer <token>"
Using basic authentication:
You can also use basic authentication and authenticate to the Splunk API using a username and a password:
curl -k -u admin:'ch@ngeM3'
Generating an API token:
A last method, but less common since the bearer token were introduced, is to authenticate using basic authentication and retrieve an API token which will be used for the REST calls purposes.
Example:
curl -k https://localhost:8089/services/auth/login --data-urlencode username=svc_splunk --data-urlencode password=pass
<response>
<sessionKey>DWGNbGpJgSj30w0GxTAxMj8t0dZKjvjxLYaP^yphdluFN_FGz4gz^NhcgPCLDkjWH3BUQa1Vewt8FTF8KXyyfI09HqjOicIthMuBIB70dVJA8Jg</sessionKey>
<messages>
<msg code=""></msg>
</messages>
</response>
export token="DWGNbGpJgSj30w0GxTAxMj8t0dZKjvjxLYaP^yphdluFN_FGz4gz^NhcgPCLDkjWH3BUQa1Vewt8FTF8KXyyfI09HqjOicIthMuBIB70dVJA8Jg"
A token remains valid for the time of a session. (1 hour by default)
The token would be used as following:
curl -k -H "Authorization: Splunk $token"
Using the REST API from the outside with curl
Consider the following REST API usage example in SPL:
| trackme url="/services/trackme/v2/vtenants/trackmeload" mode="post" body={\"mode\": \"full\"}
Using curl, it could be translated into:
curl -u admin https://localhost:8089/services/trackme/v2/vtenants/trackmeload -X POST -d '{"mode": "full"}'
Hint
JSON format
Note that the trackme SPL command understands JSON submitted with both single or double quotes, however when using a REST API endpoint from the outside of Splunk, you must submit a proper JSON object with double quotes.