TCP Proxy API

The TCP Proxy API is used for managing TCP proxy sessions for devices in your Managed IoT Cloud.

This only available as on-demand basis. Please contact your Telenor Connexion representative for more information.

Note: this API has a different ApiGatewayRootUrl than the standard APIs.

OPEN

Required role: Read
Required privilege: Things.READ on the domain of the specified Thing

Open a TCP socket on the proxy server for a thing. Connect to this socket in order to start communicating with the device.

API Endpoint: [POST]: tcpsocket/{thingName}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login

Query

  • thingName: the thing to open proxy session to required

Body

  • allowedIp: allow only connections from this IP to proxy session, if omitted or “ALL” any IP is allowed optional
  • timeoutSec: seconds proxy session port will be open before timing out, default is 60s optional

Example body

{
    "allowedIp": "10.0.0.100",
    "timeoutSec": "300"
}

Response

The hostname and port to connect to. This port will only be open for 60s.

Example response

"ec2-54-154-238-68.eu-west-1.compute.amazonaws.com:10000"

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN Returned if trying to open proxy for a thing belonging to a domain the user is not authorized to see.
THING_NOT_FOUND thingName Returned if the thing cannot be found.

CLOSE

Required role: Read
Required privilege: Things.READ on the domain of the specified Thing

Close a socket listening for new proxy sessions for a thing, and terminate any active session.

API Endpoint: [DELETE]: tcpsocket/{thingName}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login

Query

  • thingName: the thing to close proxy session torequired

Response

Confirmation of successful request.

Example response

{
  status: 'CLOSED',  
  thingName: '00000001'
}

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN Returned if trying to close proxy for a thing belonging to a domain the user is not authorized to see.
THING_NOT_FOUND thingName Returned if the thing cannot be found.

STATUS

Required role: Read
Required privilege: Things.READ on the domain of the specified Thing

Get status of proxy session for a thing.

API Endpoint: [GET]: tcpsocket/{thingName}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login

Query

  • thingName: the thing to get proxy session status forrequired

Response

  • thingName: The thing id.
  • state: Indicates status of a proxy session to the thing. open if there’s an active proxy session, closed otherwise.
  • bytesRead: Number of bytes read by thing through proxy server.
  • bytesWritten: Number of bytes written by thing through proxy server.
  • localAddress: IP address of proxy server.
  • remoteAddress: Remote IP address of connected user.
  • remotePort: Remote port of connected user.
  • remoteFamily: Remote IP family of connected user.

Example response

{
  thingName: '00000001',
  state: 'open',
  traffic: {
    bytesRead: 100,
    bytesWritten: 100
  },
  address: {
     localAddress: '::ffff:172.31.43.216',
     remoteAddress: '::ffff:83.227.22.228',
     remotePort: 65444,
     remoteFamily: 'IPv6'
  }
}

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN Returned if trying to get proxy status for a thing belonging to a domain the user is not authorized to see.
THING_NOT_FOUND thingName Returned if the thing cannot be found.