Documentation

Appearance

Remote access ​

Remote access endpoints bootstrap host and port discovery before terminal or service sessions. Use these from your backend - not from browser clients directly.

Base path: /api/remote/devices/{device_hash}/

Integration flow ​

  1. Resolve the router host for the device
  2. Open the required service (e.g. terminal)
  3. Connect your client to the returned host/port

This mirrors the dashboard remote shell flow but enforces strict organisation scoping via API key auth.

Resolve router host ​

GET /api/remote/devices/{device_hash}/host/

Returns the router host URL for remote access to the device.

bash
curl -s \
  -H "Authorization: ApiKey $ORG_API_KEY" \
  "https://gateway.dataplicity.com/api/remote/devices/$DEVICE_HASH/host/"

Open remote-access service ​

POST /api/remote/devices/{device_hash}/ports/

Open a remote-access service (terminal, or other supported service types).

bash
curl -s -X POST \
  -H "Authorization: ApiKey $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"m2m_identity": "'"$CLIENT_IDENTITY"'", "service": "terminal"}' \
  "https://gateway.dataplicity.com/api/remote/devices/$DEVICE_HASH/ports/"

Request body ​

FieldDescription
m2m_identityClient identity string for the session
serviceService to open - use "terminal" for remote shell

Returns 200 OK on success.

When to use this vs the dashboard ​

ApproachUse when
Dashboard remote shellHuman support accessing a device interactively
Gateway remote access APIYour product embeds remote access; backend opens sessions on behalf of authenticated users

Security notes ​

  • API keys must stay server-side - your backend opens ports, not the end user's browser
  • Scope remote access API keys to the minimum required organisations and devices
  • Audit who triggers remote access from your product - correlate m2m_identity with your user records