Working with Constrained Application Protocol

Start Developing Today
Working with CoAP allows you to access raw device data streams and develop your own applications and interfaces for working with your network.

Developing with CoAP APIs

The most common use case for developing with CoAP is when you would like to make use of the raw network traffic and device data in order to develop your own custom applications or integrate directly to devices.


The CoAP Gateway is a UDP-based Constrained Application Protocol (CoAP) interface that exposes a forward proxy for Read/Write access to devices on the SSN mesh network. Users of this API and documentation are expected to be familiar with CoAP functionality.

We highly recommend you read that you get familiar with CoAP and Silver Spring's implementation of the protocol by reading the CoAP Overview.


In addition, here are links to the CoAP specifications:

  • RFC 7252 - The Constrained Application Protocol (CoAP)
  • RFC 7390 - Group Communication for the Constrained Application Protocol (CoAP)
  • RFC 7641 - Observing Resources in the Constrained Application Protocol (CoAP)
  • RFC 7650 - A Constrained Application Protocol (CoAP) Usage for REsource LOcation And Discovery (RELOAD)

The CoAP Gateway functions as a standard CoAP-to-CoAP proxy and its usage primarily follows the CoAP standard. Therefore, it can be implemented with standard tools, such as the libcoap library.

Note: You might find it somewhat problematic to use the Firefox Copper (CU) CoAP add-on for proxy operations because of the requirement to establish a session. However Copper can be used for CoAP access to the proxy itself.


CoAP API Architecture Data Flow


Available CoAP Options

CoAP Gateway forwards all CoAP options to the destination endpoint server, including the Observe option for GET requests used to subscribe to resource change notifications.

Any CoAP options specifically supported by the CoAP Gateway will be described in its CoAP standard CoRE resource .well-known/core.

The CoAP Gateway forwards all CoAP options, and the Silver Spring Networks CoAP server handles all COAP methods (that is, GET, POST, PUT, DELETE).


Address Resolution

The CoAP Gateway is accessible from the internet at a domain name which is referred to throughout this document as “gatewayhost."

The CoAP Gateway performs address resolution for the client. So, in order to access a device on the mesh, you must provide the hostname with which it registers with the Silver Spring DNS server. This is referred to throughout this documentation as "domain." To access a device on the mesh the name is comprised of the prefix "ssn", the MAC address of the NIC in upper case with no colons, and the domain.


For instance,

The applicable values for the SSN Starfish Networks are provided in the following table:

Network Gatewayhost Domain
Starfish Test

Starfish Stage
Starfish Prod   TBD
Any other Ask your SSN representative Ask your SSN representative



A typical coap-client proxy request will have several ports specified in it:

coap-client -m get -p 12345 -P gatewayhost:5683 coap://devicehost:5683/.well-known/core


To break that down:

  • Client Port - the port that the client uses to send/receive CoAP traffic for this command. This is specified in coap-client using the "-p" flag. In this example the client is going to use port 12345 on the local machine to send/receive traffic. As described above it is very important to use this option consistently when communicating with Gateway so that the client's authenticated session can be looked up.
  • Proxy Port - the port that the CoAP proxy (i.e. Gateway) is listening for traffic on. This is specified as part of the Proxy-Uri, which in coap-client is the "-P" flag. In this example the client is sending requests through the proxy gatewayhost on port 5683.
  • Server Port - the port that the CoAP server (i.e. the mesh device) is listening for traffic on. This is specified as part of the target URI, in this case devicehost:5683.


The CoAP protocol has the default port number 5683, which means it is always optional to specify (just as port 80 is optional for HTTP or 443 is optional for HTTPS). By default both Gateway and SSN NIC firmware listen on the standard CoAP port 5683 so it would be equivalent to use the command:

coap-client -m get -p 12345 -P gatewayhost coap://devicehost/.well-known/core


(milliNIC devices use a different default port - 4849. This port always needs to be specified when communicating with a milli)

It is also valid to tell the client to use port 5683 (i.e. -p 5683)  as long as a CoAP server is not running on the same system and already using that port. However, it can be confusing to differentiate the meaning and destination of commands if client, proxy, and server are all using the same ports.  The examples below will continue to use 12345 as the client port for clarity. 



CoAP API calls are secured using an OAuth token. Authentication and granting of a token requires an API key (ClientID and Secret). Details of API authentication can be found in the Security section of the API Overview page.


Sessions are associated with the client account configured on the CoAP Gateway. The default configuration allows a maximum of 10 concurrent sessions per account, but each must bind to a unique socket on which to receive its responses. By default, the Gateway is configured to close sessions that have been idle for more than four hours (with a 15 minute grace period). Sessions can also be closed explicitly via a DELETE operation on the /sessions URI.

Establishing a session

Clients can establish a CoAP Gateway session using a token which can be obtained using the tokens API.  Refer to the Security section of the API Overview for security, authentication, and how to obtain a token to call APIs. The session is established by POSTing the token as a plain text UTF-8 body to the Gateway's /sessions resource.


  • The "-t 0" specifies the content type of the message as UTF-8.
  • The "-f -" means that the content should be read from STDIN (i.e. the echoed text)


The session will be rejected if the token is expired, unparsable, or not a signed token.


Terminate a session

Once you are finished, you SHOULD delete your session. To close a CoAP Gateway proxy session on port 5683:

coap-client -v 10 -m delete -p 5683  "coap://gatewayhost:5683/sessions"

If the session is successfully deleted Gateway will respond with a DELETED_202 (message code 66) message.  If the deletion fails for any reason Gateway will respond with a PRECONDITION_FAILED_412 (message code 140) response.

Idle sessions may also be kicked from the Gateway.  A session is considered idle if traffic has not been sent or received between the client and Gateway for more than the configured maxSessionIdleTime (defaults to 4 hours).  When a session times out, Gateway will send the client a non-confirmable CoAP response SERVICE_UNAVAILABLE_503 (message code 163) message.

Any further requests made on a closed session will be rejected with a UNAUTHORIZED_401 (message code 129) response, indicating that the client needs to re-authenticate.

Testing with libcoap 

To get the CoAP client and server programs in your path for testing purposes, you can install libcoap and test CoAP calls as shown in the examples below. 


Given CoAP Gateway running on gatewayhost (see table above) and a device (aka "server") running on NIC mac address 001350050005E7D6 (SSN001350050005E7D6) at domain (see table above), libcoap can be used to test as in the examples below.

Establish a Connection

To establish a session for UDP traffic on port 5683:

Get CoAP Resources 

To get CoAP resources on the device NIC behind the CoAP Gateway proxy:

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap://SSN001350050005E7D6.domain:5683/.well-known/core


Get NIC Time 

To get the time on the device NIC behind the CoAP Gateway proxy:

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap://SSN001350050005E7D6.domain:5683/time


Get NIC GPIO Pin Description 

To get a description of the GPIO pins available on the device NIC behind the CoAP Gateway proxy:

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap:// SSN001350050005E7D6.domain:5683/gpio


Terminate a session

Once you are finished, you SHOULD delete your session. To close a CoAP Gateway proxy session on port 5683:


Attempt to Get CoAP Resource Not Implemented 

Attempting to get a CoAP resource that has not been implemented on a device behind CoAP Gateway proxy should result in a “5.01 Not Implemented” error. 

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap:// SSN001350050005E7D6.domain:5683/dummy


Attempt to Get CoAP Resources without a Session or without Permission

Attempting to access a device behind CoAP Gateway proxy without a session should result in a “4.01 unauthorized” internal error. Similarly, attempting to access a device without the appropriate permission should display the “4.01 unauthorized” internal error.

coap-client -v 10 -m get -p 5683 -P gatewayhost:5683 coap://devicehost:5683/.well-known/core

Seeking help from the CoAP Gateway

A client can send a request to coap://gatewayhost/help by issuing this command:
coap-client -m get -p 54321 coap://

The Gateway responds with
v:1 t:CON c:GET i:40cf {} [ ]
To login, send POST to /sessions
To have your session follow your account across different clients, include the query parameter '&sticky=true'.
To logout, send DELETE to /sessions.
To echo a payload, send POST to /echo.