Teltonika networks

#Tutorials

The tutorials section is a collection of tutorials that will help you get started with the API.

You can use tools like Postman or Insomnia to make API requests. The tutorials will be using cURL.

#Table of Contents

#Making your first request

For this tutorial we will be getting detailed information of your device by using the GET /api/system/device/status endpoint.

First of all make sure your device is accessible on the network you are connected to and you know it’s IP address, login and password.

Before you make any request you need to authenticate to the device. To do that you need to send a request to POST /api/login endpoint:

curl -X POST "http://<DEVICE_IP>/api/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "<USERNAME>", "password": "<PASSWORD>"}'

Make sure to replace <DEVICE_IP>, <USERNAME> and <PASSWORD> with your device IP address, login and password.


The response should have a property ubus_rpc_session which is your session token. The token expires after 5 minutes so you will need to reauthenticate after that time to get a new token. More information here.

For the next step we will be using the token we received in the previous step. To do that we need to add a header Authorization: Bearer <SESSION_TOKEN> to our request with the value of the token we received.

Let’s make a request to GET /api/system/device/status endpoint:

curl -X GET "http://<DEVICE_IP>/api/system/device/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SESSION_TOKEN>"

You should now receive a response with detailed information about your device.

#Service configuration

This tutorial will show you how to do basic configuration of a service. Most services implement basic CRUD operations (Create, Read, Update, Delete).

In this tutorial we will be using the Wireguard service as an example, but most other services can be configured in a similar way. See API reference for more information about specific services.


Please note that Wireguard may not be supported on your device. Consult the datasheet of your device to see if it’s supported.


Before starting make sure you know how to authenticate and use the session token. More information here.

#Getting configuration instances

To get a service configuration instance you can either get a list of all instances or get a specific instance by it’s ID.

To get all instances send a request to GET /api/wireguard/config endpoint:

curl -X GET "http://<DEVICE_IP>/api/wireguard/config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SESSION_TOKEN>"

If there are no instances you should receive an empty array as a response, otherwise the response should look like this:

{
    "success": true,
    "data": [
        {
            "enabled": "1",
            "private_key": "kHEaUxFiK6VstuI5gva7Zp79g19w+TV3knejZMh5dFg=",
            ".type": "interface",
            "id": "example",
            "addresses": [
                "1.1.1.1/24"
            ],
            "listen_port": "51820",
            "public_key": "JgUB/QFv23t5JoYGQEQtmhJm2OiBWe2XDIbpIbdWkyI="
        }
    ]
}

To get an instance of, for example, id example send a request to GET /api/wireguard/config/example endpoint:

curl -X GET "http://<DEVICE_IP>/api/wireguard/config/example" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SESSION_TOKEN>"

#Creating a new instance

To create a new instance send a request to POST /api/wireguard/config endpoint:

curl -X POST "http://<DEVICE_IP>/api/wireguard/config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SESSION_TOKEN>" \
  -d '{"data": {"id": "test"}}'

Consult the API reference to see what options are available for the service you are configuring.

This will create a new instance with id test and return the instance as a response:

{
    "success": true,
    "data": {
        "enabled": "0",
        "private_key": "2HtMECpMqr4bOs+7OYmjx0W2o5Mr01DlBk4H/TjgxFk=",
        "id": "test",
        ".type": "interface",
        "listen_port": "51820",
        "public_key": "avsG25Z/7Mbt3jNbx/NaHfllxnK9kvXqYhgrTlAbJUc="
    }
}

#Updating an instance

To update an instance send a request to PUT /api/wireguard/config/<ID> endpoint. Replace <ID> with the id of the instance you want to update.

Let’s enable the Wireguard instance we created in the previous step by providing the enabled option in the request body:

curl -X PUT "http://<DEVICE_IP>/api/wireguard/config/test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SESSION_TOKEN>" \
  -d '{"data": {"enabled": "1"}}'

This will enable the instance and return it as a response:

{
    "success": true,
    "data": {
        "enabled": "1",
        "private_key": "2HtMECpMqr4bOs+7OYmjx0W2o5Mr01DlBk4H/TjgxFk=",
        "id": "test",
        ".type": "interface",
        "listen_port": "51820",
        "public_key": "avsG25Z/7Mbt3jNbx/NaHfllxnK9kvXqYhgrTlAbJUc="
    }
}

#Deleting an instance

To delete an instance send a request to DELETE /api/wireguard/config/<ID> endpoint. Replace <ID> with the id of the instance you want to delete.

curl -X DELETE "http://<DEVICE_IP>/api/wireguard/config/test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SESSION_TOKEN>"

If the instance was deleted successfully you should receive the following response:

{
    "success": true,
    "data": {
        "id": "test"
    }
}

#Working with files

Some services require you to upload files to the device. In such cases you can either use endpoints included with a service to upload a file to the device or you can manually upload and set the path to the file in the service configuration.

#Uploading files

To upload a file using an endpoint included with a service, send a POST request to the endpoint with the Content-Type header set to multipart/form-data and the file included in the request body.

Uploading a new root Certificate Authority (CA) file:

{
    "method": "POST",
    "url": "/api/certificates/root_ca/config",
    "headers": {
        "Content-Type": "multipart/form-data",
        "Content-Disposition": "form-data; name=\"<NAME>\"; filename=\"<FILE_NAME>\"",
        "Authorization": "Bearer <AUTH_TOKEN>"
    },
    "body": {
        "data": {
            "<NAME>": "<FILE>"
        }
    }
}

Most HTTP clients will automatically set the Content-Type and Content-Disposition headers to correct values when you include a file in the request body.

To use an uploaded file in a service, you need to set the path to the file in the service configuration. The path to the file is returned in the response after uploading a file.

For example, after uploading a root CA file, the response will contain the path to the file:

{
    "success": true,
    "data": {
        "path": "/etc/cacert.pem"
    }
}

#Working with certificates

Some services require you to use certificates to secure the connection. To use certificates, you need to upload them to the device and then set the path to the certificate in the service configuration. Refer to the section above to find out about working with files.

#Simple certificate generation

In order to simplify certificate generation, you can use POST /api/certificates/actions/generate endpoint to generate certificates for most use cases.

Generated files:

  • 3 certificates:
    • ca.cert.pem - CA certificate
    • server.cert.pem - Server certificate
    • client.cert.pem - Client certificate
  • 4 keys:
    • ca.key.pem - CA key
    • server.key.pem - Server key
    • client.key.pem - Client key
    • dh.pem - Diffie-Hellman key

Certificates may take some time to generate.


To start generating certificates send a request to POST /api/certificates/actions/generate endpoint with the following body:

{
    "data": {
        "type": "simple"
    }
}

To see all the generated and generating certificates send a request to GET /api/certificates/config:

{
    "success": true,
    "data": {
        "generated": [
            {
                "type": "key",
                "name": "ca",
                "timestamp": "-",
                "cert_type": "ca",
                "key_size": "2048",
                "fullname": "ca.key.pem"
            },
            {
                "type": "cert",
                "name": "ca",
                "timestamp": "1989580217",
                "cert_type": "ca",
                "key_size": "2048",
                "fullname": "ca.cert.pem"
            },
            {
                "type": "key",
                "name": "server",
                "timestamp": "-",
                "cert_type": "server",
                "key_size": "2048",
                "fullname": "server.key.pem"
            },
            {
                "type": "cert",
                "name": "server",
                "timestamp": "1989580217",
                "cert_type": "server",
                "key_size": "2048",
                "fullname": "server.cert.pem"
            },
            {
                "type": "key",
                "name": "client",
                "timestamp": "-",
                "cert_type": "client",
                "key_size": "2048",
                "fullname": "client.key.pem"
            },
            {
                "type": "cert",
                "name": "client",
                "timestamp": "1989580217",
                "cert_type": "client",
                "key_size": "2048",
                "fullname": "client.cert.pem"
            }
        ],
        "generating": [
            {
                "type": "dh",
                "fullname": "dh.pem"
            }
        ]
    }
}

All generated certificates are stored in /etc/certificates/ folder on your device


Now when configuring a service, you can use a generated certificate by providing a path to a certificate in the file system of your device. To reference a certificate with the name of client.cert.pem you should prefix it with /etc/certificates, resulting in: /etc/certificates/client.cert.pem.

Refer to the API reference to find out more about the possibilities of generating certificates.

BETA