API Overview

This document describes the REST API endpoints provided by the iotcomms.io platform. These APIs allow you to provision services and interact with their execution—from managing users and devices to handling calls, media, recordings, and more.

Before diving into the API endpoints, ensure you have completed the following prerequisites:

1. Account and Domain Setup

   Make sure you have an active account on the iotcomms.io platform and that your domain (formed by your unique subdomain and the region-specific parent domain) is provisioned correctly. For example, a customer with the subdomain customer47 in the Stockholm region will have the full domain:

   customer47.prod-eu-north-1.iotcomms.io
   

   This is represented as {domain} in the API documentation.

2. Key Pair Generation and Management

   There are two distinct key pairs used in the iotcomms.io ecosystem:

   • API Access Key Pair

     For making API calls to the iotcomms.io platform, you (the customer) must generate an RS256 key pair. Upload your public key via the CONFIGURATIONS / API ACCESS / UPLOAD JWT PUBLIC KEY page. This key pair is used to sign and verify your JWT tokens for authenticating API requests.

   • Callback Signing Key Pair

     For service callbacks (i.e., when the iotcomms.io platform sends events to your system), a separate key pair is used. The private key used to sign these callback requests is configured through the notification or service configuration. This can be done via the web UI at:

     • /configuration/notification

     • /configuration/alarmbridge

     • /configuration/mediaservice

     Alternatively, the provisioning APIs for these services can be used. The iotcomms.io platform will use the corresponding public key (associated with the configured private key) to allow you to verify the authenticity of the callback requests.

   Generating the API Access Key Pair: A sample script to generate your API access key pair using openssl:

   #!/bin/bash
   openssl genrsa -out private.pem 2048
   openssl rsa -in private.pem -pubout -out public.pem
   

3. Development Environment

   Set up your development environment with your preferred API testing tools (e.g., Postman, curl) and a Node.js runtime for sample code.

4. JWT Generation

   Familiarize yourself with JWT token creation. The token must be signed with your API access private key and include claims such as sub (your domain), iat (issued at timestamp), and optionally exp (expiration timestamp, with a maximum validity of 90 minutes).

Quick Start Guide

Follow these steps to make your first API call:

1. Generate a JWT

   Use the following Node.js example to generate a JWT token. Ensure you have installed the jsonwebtoken package (npm install jsonwebtoken):

   const jwt = require('jsonwebtoken');
   const fs = require('fs');
   
   // Load your API access private key from file
   const privateKey = fs.readFileSync('private.pem', 'utf8');
   
   // Define your payload
   const payload = {
       sub: 'customer47.prod-eu-north-1.iotcomms.io', // your domain
       iat: Math.floor(Date.now() / 1000),
       exp: Math.floor(Date.now() / 1000) + (90 * 60) // valid for 90 minutes
   };
   
   // Sign the JWT using RS256
   const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });
   console.log('JWT Token:', token);
   

2. Make a Sample API Request

   Use the correct base URL for your region. For example, for the Stockholm region, the base URL is:

   api.prod-eu-north-1.iotcomms-io
   

   Here’s a sample curl command to perform a GET request:

   curl -X GET "https://api.prod-eu-north-1.iotcomms-io/<endpoint>" 
   
       -H "Authorization: Bearer <Your_JWT_Token>"
   

3. Response Handling

   Check the HTTP status code and response body to confirm the request was successful. Common status codes include:

   • 200 OK

     Request was successful.

   • 401 Unauthorized

     The JWT may be expired or invalid.

   • 403 Forbidden

     Your domain or credentials might not have the required permissions.

The iotcomms.io API is a RESTful service that uses standard HTTP methods such as OPTIONS, GET, PUT, POST, DELETE, and PATCH. In addition, you can configure callbacks that trigger actions in response to events (for example, when a new call is received or an alarm is generated).

Every request to the API must be authenticated using a JWT bearer token that is signed with your API access private key. The corresponding public key must be uploaded during provisioning via the API access configuration.

All API endpoints share a common base URL that depends on the deployment region. For example, the Stockholm region uses:

api.prod-eu-north-1.iotcomms-io

Customer-specific endpoints include a unique domain identifier, as described below.

Each customer is identified by a unique subdomain. Combined with the region-specific parent domain, this forms the complete domain used for SIP request routing and API access. For example, a customer with the subdomain customer47 in the Stockholm region will have the full domain:

customer47.prod-eu-north-1.iotcomms.io

In the API documentation, this is represented by the placeholder {domain}.

Before accessing the APIs, you must generate an RS256 key pair and provision the public key on the iotcomms.io platform. The public key is used by the platform to validate your JWT signatures, while the private key must remain confidential.

Important:

• The public key (for API access) can be shared without risk, as it only verifies the signature.

• If the private key is compromised, generate a new key pair immediately and update the configuration.

A recommended method for key generation is using openssl. For example, the following bash script generates the required keys:

#!/bin/bash
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

After generating the keys, upload the public key via the CONFIGURATIONS / API ACCESS / UPLOAD JWT PUBLIC KEY page. This page also allows you to verify that your JWTs are valid.

To restrict API access to authorized users, every API call must include authentication information. The recommended approach is to include a JWT bearer token in the HTTP Authorization header:

Authorization: Bearer <JWTToken>

The token must be constructed according to the guidelines below. JWTs include issuance and expiration times, ensuring that tokens cannot be reused indefinitely. Note that the API does not issue JWTs as part of an authorization process; you must create and sign them yourself.

For additional details on JWT tokens, visit jwt.io. A JWT token consists of three parts: the header, payload, and signature, formatted as:

<header>.<payload>.<signature>

JWT Header

The header specifies the token type and the algorithm used for the signature. iotcomms.io uses the RS256 algorithm. An example header:

{
    "alg": "RS256",
    "typ": "JWT"
}

JWT Payload

The payload carries the claims. For authentication, include the following fields:

{
    "sub": "customer47.prod-eu-north-1.iotcomms.io",
    "iat": 1600327269,
    "exp": 1600338000
}

• sub

  The subject (i.e., your domain) is mandatory.

• iat

  The issued-at timestamp (in Unix time) is mandatory. Tokens older than one hour will be rejected.

• exp

  The expiration timestamp (in Unix time) is optional but cannot exceed 90 minutes from the issuance time.

JWT Signature

The signature is created using your private key and the RS256 algorithm. It ensures the integrity of the token and verifies that it was issued by an authorized party.

Since the JWT is not generated by the platform, it is your responsibility to create and sign it. When a request is received:

1. The platform verifies that the sub field matches a provisioned domain.

2. The stored public key for that domain is used to validate the signature.

3. The iat field is checked to ensure the token is not too old.

This mechanism prevents impersonation, as only a token signed with the correct private key will be validated against the corresponding public key.

You can also use the CONFIGURATIONS / API ACCESS / UPLOAD JWT PUBLIC KEY page to verify the validity and correctness of your JWTs.

Some services on the iotcomms.io platform use REST callbacks to notify your system about events (for example, when an incoming SIP MESSAGE is received, triggering a POST request to CALLBACK_BASE_URL/message).

• CALLBACK_BASE_URL

  is configured in the iotcomms.io platform and points to your API endpoint that will receive callback requests.

• Detailed information about callback endpoints can be found in the API documentation under the implicit_callbacks and callbacks sections.

Callback Authentication

Callback requests support multiple authentication methods:

• JWT Authentication

  Uses the same JWT mechanism as REST endpoints. The iotcomms.io platform uses a separate key pair for signing callback requests. Configuration: The private key used to sign callback requests is set via the notification or service configuration. This can be configured through the web UI at:

  • /configuration/notification

  • /configuration/alarmbridge

  • /configuration/mediaservice

  Alternatively, you can configure it using the provisioning APIs for these services. This key pair is independent of the API access key pair.

• Token or Basic Authentication

  Configured in the notification settings. The appropriate token is added to the Authorization header as a Basic or Bearer token.

Most endpoints support the OPTIONS method to allow clients to query which HTTP methods are available. As per RFC 2616: > The OPTIONS method requests information about the communication options available on the request/response chain identified by the Request-URI. This method enables the client to determine the options or requirements associated with a resource without initiating a resource retrieval. A successful OPTIONS request will return a 200 OK status and include an Allow header specifying the supported methods for that endpoint.

When supported, the PATCH method is used to modify specific properties of a resource. The request must be formatted as follows:

<resourcepath>/{domain}/{resourceId}

For example:

PATCH /device/myDomain.iotcomms.io/12345

The request body is an array of operations, as specified in RFC 6902. For example:

[
    { "op": "replace", "path": "/authType", "value": "credentials" }
]

In this example, the authType of the device is changed to credentials.

Notes:

• resourcepath

  The path for the specific resource (e.g., device, trunk).

• {domain}

  The domain to which the resource is provisioned.

• {resourceId}

  The unique identifier for the resource. For devices, this is chosen during provisioning; for trunks, it is generated by iotcomms.io.

• JWT Documentation

  Learn more about JWT tokens at jwt.io.

• Comprehensive API Reference

  For a detailed description of all API endpoints, see the full API documentation at /documentation/our-apis.

• Postman Collection

  Look for a Postman collection provided by the iotcomms.io team for pre-configured requests to help you get started quickly.

• Community and Support

  Visit the support forums or contact support if you encounter any issues or need further assistance.