Using Postman to execute SaltStack Enterprise API
The SaltStack Enterprise API REST interface is made through an HTTP(s) bridge. The bridge accepts JSON payloads POSTed to an endpoint exposed by SSE, translates the payloads into RPC calls, then returns the result as JSON. The endpoint supports cookie-based authentication so authentication credentials need to be passed only once per session. The bridge also allows sending multiple calls in a single payload.
- Download and install the
postman
client application: https://www.getpostman.com/postman - Set SSL certificate validation off
- Import
SaltStack eAPI.postman_collection.json
(attached to this article). - Set the collection user and password for authentication.
- Set the variable for host.
If xsrf is enabled (default with state install) in the /etc/raas/raas.conf tornado_xsrf_cookies_enabled: True
you will need to provide the X-Xsrftoken:
on the header of the rest call. The best way is to save a cookie with a GET
call then use the cookie to provide the header token. This cookie is saved in the $HOME
(users home) directory. The payload is a dictionary. If you donʼt care about xsrf then you can set the tornado_xsrf_cookies_enabled
value to False
and the need for the X-Xsrftoken
is no longer required.
Example curl call with xsrf header
curl -k -c $HOME/eAPICookie.txt -u root:salt 'https://localhost/version'/ > dev/null
curl -k -u root:salt -b $HOME/eAPICookie.txt -H 'X-Xsrftoken: ' $(grep -w '_xsrf' $HOME/eAPICookie.txt | cut -f7)'' -X POST https://localhost/rpc -d '{"resource": "admin", "method": "trim_database", "kwarg": { "audit": 30, "events": "30", "jobs": "30", "test": "True" }}
Postman by default will use cookies and the header data is available and can be assigned to variables. For XSRF (default) we set up the cookie variables with the GET
command.
Any subsequent calls use the X-Xsrftoken
header.
All commands use the rpc
REST endpoint (https://servername/rpc
). The data that is passed is a JSON payload consisting of the following:
{ "resource": "interface_name", "method": "method_name", "kwarg": { "keyword_argument": "keyword_value", ... } }
resource
: value is the name of the interface you will use
method
: value is the name of the method you will use
kwarg
: value is the keyword arguments that are needed for the method.
Lists are contained in []
with comma separated items.
Example payload for cmd
resource and route_cmd
method: (wheel
command)
{ "resource": "cmd", "method": "route_cmd", "kwarg": { "cmd": "wheel", "masters": [ "master3_master" ], "fun": "key.accept_dict", "arg": { "arg": [ { "minions": [ "master3", "master2" ], "minions_denied": [], "minions_pre": [], "minions_rejected": [] } ], "kwarg": { "include_denied": "True", "include_rejected": "True" } } } }
Example payload for cmd
resource and route_cmd
method: (salt
command)
{ "resource": "cmd", "method": "route_cmd", "kwarg": { "cmd": "local", "fun": "cmd.run", "arg": { "arg": [ "ls /etc" ] }, "tgt": { "*": { "tgt": "*", "tgt_type": "glob" } } } }
Example of call with no parameters
{"resource": "api", "method": "get_versions"}
Example of auth
resource save_role
method
{ "resource": "auth", "method": "save_role", "kwarg": { "role_name": "Test Role", "perms": [ "minion-delete", "cmd-ssh-write" ] } }