Documentation

Automate your tasks with API calls

sshreach.me allows you to automate your tasks by using API calls.

The following API calls are available:

  • connect
  • disconnect
  • client_status
  • set_allow_clientless

The endpoint for API calls is the following: https://sshreach.me/init/api/API_CALL where API_CALL stands for the actual API command.

API commands require additional parameters. You can get the API call scaffolding with parameters by clicking on the copy icon in the API CALL column on the Script tab, which will result in something like this:

https://sshreach.me/init/api/API_CALL?dbid=S3iusSD710sLLaa92Ka2&host_uuid=8s0ss21z-9a11-s810-s17l-sf91lksdf878&ports_id=5621&user_id=1234

You need to replace the API_CALL with the actual command.


connect and disconnect:

With these two calls, you can open your tunnel(connect) or close it (disconnect) for the chosen client.

API calls return the following json:

{"message": "OK", "error_code": 0, "success": true}

The values can be the following:

success: true if api call succeeded, otherwise false

message: "OK" or error description

error_code values:

    00 - ok
    11 - not connected
    12 - not disconnected
    21 - invalid api call
    22 - Too many API calls
    23 - Client blocked
    24 - Client inactive
    31 - Wrong data

client_status:

This api call returns the status of the chosen client (offline or online)

{"message": "online", "error_code": 0, "success": true} or

{"message": "offline", "error_code": 24, "success": true}

set_allow_clientless:

set_allow_clientless sets the allow clientless connection value for the chosen client. This is useful if you want to replace your client script. If allow clientless connection is switched off, the forwarding server will close the tunnel as soon as it detects that the client is offline. During the replacement of the client script, it needs to be restarted, so it is advised that this option is turned on before stopping the client script and that this option is turned off afterwards for increased security.

additional parameters: allow=true|false

Example:

https://sshreach.me/init/api/API_CALL?dbid=S3iusSD710sLLaa92Ka2&host_uuid=8s0ss21z-9a11-s810-s17l-sf91lksdf878&ports_id=5621&user_id=1234&allow=true

Return values:

{"allow_clientless": true, "message": "success", "error_code": 0, "success": true}


Examples

bash:

   #!/bin/bash
   # open a tunnel to the remote machine
   result=$(curl 'https://sshreach.me/init/api/connect?dbid=Bad9alsdS920a11-Aqj2&host_uuid=20sldd20-20sz-aa20-aa02-aa0salskd82a&ports_id=1234&user_id=12345' | jq -r '.success')
   if [ "$result" = "true" ]; then
	# execute remote command
	ssh -p 12345 -i IDENTITY_FILE username@fw1.sshreach.me ls
	# and close the tunnel
	curl 'https://sshreach.me/init/api/disconnect?dbid=Bad9alsdS920a11-Aqj2&host_uuid=20sldd20-20sz-aa20-aa02-aa0salskd82a&ports_id=1234&user_id=12345'
else
	echo "error message goes here"
   fi

python:

  import urllib2
  import paramiko
  import json

  api_endpoint = 'https://sshreach.me/init/api/{0}?dbid=Bad9alsdS920a11-Aqj2&host_uuid=20sldd20-20sz-aa20-aa02-aa0salskd82a&ports_id=1234&user_id=12345'

  # open the tunnel
  json_result = json.loads(urllib2.urlopen(api_endpoint.format('connect')).read())

  if json_result['success'] == True:

	# prepare an ssh client
	client = paramiko.SSHClient()
	client.set_missing_host_key_policy(paramiko.AutoAddPolicy())

	# connect to your server
	client.connect('fw1.sshreach.me', port=12345, username='username',
		key_filename='path_to_your_key_filename')

	# execute a remote command
	stdin, stdout, stderr = client.exec_command("ls")
	if not stderr.readlines():
		for line in stdout.readlines():
			print line
	else:
		# report error
		pass

	client.close()

	# close the tunnel
	json_result = json.loads(urllib2.urlopen(api_endpoint.format('disconnect')).read())

	if json_result['success'] != True:
		# report error if tunnel wasn't closed
		pass
  else:
	print json_result['message']