Skip to content

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/developer/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/developer/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/developer/devices/$DEVICE_HASH/host/"

Open remote-access service #

POST /api/developer/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/developer/devices/$DEVICE_HASH/ports/"

Request body #

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

Host lookup requires developer:devices:read (or developer:devices:write). Opening a service requires developer:devices:write or its mcp:write alias. The selected device must belong to a Device Class owned by the key's organisation; allocated-customer access policy and active-device entitlement also apply.

GET .../host/ returns {"m2m_url": "https://.../m2m/"}. The service-open response comes from the router and depends on the requested service.

Supported services are terminal, redirect-port, and remote-file. For redirect-port, also supply port (1 to 65535) and use a port permitted by the organisation. For remote-file, also supply an allowed path.

The /api/remote/devices/... routes are for signed-in application users. They reject organisation API keys; use the developer routes shown here for API-key integrations.

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