Skip to content

connect.md

Latest commit

 

History

History
772 lines (668 loc) · 21.4 KB

connect.md

File metadata and controls

772 lines (668 loc) · 21.4 KB
Raw
id connect
title Sauce Connect API Endpoints
sidebar_label Sauce Connect
description Retrieve information about or close your Sauce Connect tunnels.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Use the Sauce Connect API methods to monitor and clean up your active proxy tunnels.

To download Sauce Connect, see Sauce Connect Installation.

Refer to Getting Started for Authentication and Server information.

What You'll Need

Get Tunnels for a User

GET /rest/v1/{username}/tunnels

Returns Tunnel IDs or Tunnels Info for any currently running tunnels launched by or shared with the specified user. It also allows to filter tunnels using an optional "filter" parameter that may take the following values:

  • filter=v2alpha - a response will contain only tunnels that were started with --vm-version v2alpha.
  • filter=one_per_pool - a response will contain only one (arbitrary) tunnel per tunnel pool.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the user whose tunnels you are requesting.
full

| QUERY | OPTIONAL | BOOLEAN |

Set to true to return all the tunnels info and not just IDs. Defaults to false.

all

| QUERY | OPTIONAL | BOOLEAN |

Set to true to return the tunnels IDs/info for all the tunnels shared with the specified user. If this option is set, the response type would be a dictionary mapping user name to a list of tunnels. Defaults to false.

filter

| QUERY | OPTIONAL | STRING |

Predefined filter name that can be used to filter out the tunnels. Currently the following filters are supported: one_per_pool, v2alpha.

<Tabs groupId="dc-url" defaultValue="US-West" values={[ {label: 'US-West', value: 'US-West'}, {label: 'US-East', value: 'US-East'}, {label: 'EU-Central', value: 'EU-Central'}, ]}>

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-4.saucelabs.com/rest/v1/jim.smith/tunnels' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels' \
--header 'Content-Type: application/json' | json_pp

Responses

200 Success.
404 Not found. 
['28e7c8133ede4588a891666dd35af1f8']
[
    {
        "owner": "jim.smith",
        "team_ids": [...],
        "creation_time": 1618345938,
        "domain_names": null,
        "owner": "jim.smith",
        "id": "28e7c8133ede4588a891666dd35af1f8",
        "extra_info": "{…}",
        …
        "tunnel_identifier": "jim.smith_tunnel_id"
    }
]
{
    "jim.smith": [
        "28e7c8133ede4588a891666dd35af1f8"
    ]
}
{
    "jim.smith": [
      {
          "owner": "jim.smith",
          "team_ids": [...],
          "creation_time": 1618345938,
          "domain_names": null,
          "owner": "jim.smith",
          "id": "28e7c8133ede4588a891666dd35af1f8",
          "extra_info": "{…}",
          …
          "tunnel_identifier": "jim.smith_tunnel_id"
      }
    ]
}

Get Tunnel Information

GET /rest/v1/{username}/tunnels/{tunnel_id}

Returns information about the specified tunnel.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the owner of the requested tunnel.
tunnel_id

| PATH | REQUIRED | STRING |

The unique identifier of the requested tunnel.

<Tabs groupId="dc-url" defaultValue="US-West" values={[ {label: 'US-West', value: 'US-West'}, {label: 'US-East', value: 'US-East'}, {label: 'EU-Central', value: 'EU-Central'}, ]}>

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-4.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Responses

200 Success.
404 Not found. 
{
    "owner": "jim.smith",
    "team_ids": [...],
    "creation_time": 1618345938,
    "domain_names": null,
    "id": "28e7c8133ede4588a891666dd35af1f8",
    "extra_info": "{…}",
    "direct_domains": null,
    "vm_version": "",
    "no_ssl_bump_domains": null,
    "shared_tunnel": false,
    "metadata": {...},
    "status": "running",
    "is_ready": true,
    "shutdown_reason" : null,
    "shutdown_time" : null,
    "user_shutdown": null,
    "host": "maki3429.miso.saucelabs.com",
    "ip_address": null,
    "last_connected": 1618346660,
    "launch_time": 1618345940,
    "tunnel_identifier": "jim.smith_tunnel_id"
}

Get Tunnel Version Downloads

GET /rest/v1/public/tunnels/info/versions

Returns tunnel version download information.

Parameters

client_version

| QUERY | OPTIONAL | STRING |

Returns download information for the specified Sauce Connect client version (For example, 4.7.1).
client_host

| QUERY | OPTIONAL | STRING |

Returns download information for the Sauce Connect Proxy version with the specified host OS and CPU Architecture (For example, darwin-amd64).

all

| QUERY | OPTIONAL | BOOLEAN |

Set to `true` to return download information for all available Sauce Connect Proxy versions. Defaults to `false`.

<Tabs groupId="dc-url" defaultValue="US-West" values={[ {label: 'US-West', value: 'US-West'}, {label: 'US-East', value: 'US-East'}, {label: 'EU-Central', value: 'EU-Central'}, ]}>

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/public/tunnels/info/versions' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-4.saucelabs.com/rest/v1/public/tunnels/info/versions' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/public/tunnels/info/versions' | json_pp

Responses

200 Success.
404 Not found. 
{
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "osx" : {
         "download_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect-5/installation/",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect-4/installation",
   "latest_version" : "4.9.2",
   "warning" : [
      "Client host platform is not specified, the download URL cannot be determined"
   ]
}
{
   "all_downloads" : {
      "4.7.0" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.0-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.0-osx.zip",
            "sha1" : "<hash>"
         }
      },
      "4.7.1" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.8.0" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.8.1" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.8.2" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.9.0" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.9.1" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.9.2" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
            "sha1" : "<hash>"
         }
      }
   },
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect-4/installation",
   "latest_version" : "4.9.2",
   "warning" : [
      "Client host platform is not specified, the download URL cannot be determined"
   ]
}
{
   "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect-4/installation",
   "latest_version" : "4.9.2",
   "sha1" : "<hash>"
}
{
   "client_version" : "4.7.1",
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect-4/installation",
   "latest_version" : "4.9.2",
   "status" : "UPGRADE",
   "warning" : [
      "Client host platform is not specified, the download URL cannot be determined"
   ]
}

Get Current Jobs for a Tunnel

GET /rest/v1/{username}/tunnels/{tunnel_id}/num_jobs

Returns the number of currently running jobs for the specified tunnel.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the user whose tunnels you are requesting.
tunnel_id

| PATH | REQUIRED | STRING |

The unique identifier of the requested tunnel.

<Tabs groupId="dc-url" defaultValue="US-West" values={[ {label: 'US-West', value: 'US-West'}, {label: 'US-East', value: 'US-East'}, {label: 'EU-Central', value: 'EU-Central'}, ]}>

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8/num_jobs' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-4.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8/num_jobs' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8/num_jobs' \
--header 'Content-Type: application/json' | json_pp

Responses

200 Success.
404 Not found. 
{
    "id": "28e7c8133ede4588a891666dd35af1f8",
    "jobs_running": 1
}

Stop a Tunnel

DELETE /rest/v1/{username}/tunnels/{tunnel_id}

Shuts down the specified tunnel.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the user whose tunnels you are requesting.
tunnel_id

| PATH | REQUIRED | STRING |

The unique identifier of the tunnel to stop.

<Tabs groupId="dc-url" defaultValue="US-West" values={[ {label: 'US-West', value: 'US-West'}, {label: 'US-East', value: 'US-East'}, {label: 'EU-Central', value: 'EU-Central'}, ]}>

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-east-4.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Responses

200 Success.
404 Not found. 
{
    "result": true,
    "id": "28e7c8133ede4588a891666dd35af1f8",
    "jobs_running": 0
}