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.

1. Download and install the postman client application: https://www.getpostman.com/postman
2. Set SSL certificate validation off
   
3. Import SaltStack eAPI.postman_collection.json (attached to this article).
4. Set the collection user and password for authentication.
   
5. 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"
    ]
  }
}