Getting started

This guide will walk you through the basic steps to start using Navixy Repository API. You'll learn how to authenticate, create an inventory and an inventory item to store your GPS device, and activate it.

Prerequisites

Before you begin, ensure you have:

• Valid Navixy Repository API credentials (client_id and client_secret).

• A registered Callback URL (Redirect URI): The specific URL in your application where users will be redirected after granting consent.

• URLs of API and authentication servers ({BASE_URL} and {AUTH_BASE_URL}), determined depending on your geographical location and the current version of the API. For more information about {BASE_URL}, see API environments. For information about {AUTH_BASE_URL}, see Authentication environments.

• A secure method to generate and validate the state parameter for Cross-Site Request Forgery (CSRF) protection.

• A GPS device ready for activation that belongs to the list of supported devices.

Step 1. Authentication

Navixy Repository API supports the OAuth2 Authorization Code Flow. To acquire an access token, follow these steps:

1

Redirect users to the authorization endpoint

curl -L \
  --request GET \
  --url "{AUTH_BASE_URL}/realms/users/protocol/openid-connect/auth" \
  --data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'redirect_uri=https://<YOUR_APP_CALLBACK_URL>' \
  --data-urlencode 'scope=<REQUESTED_SCOPE_ONE> <REQUESTED_SCOPE_TWO>' \
  --data-urlencode 'state=<YOUR_SECURE_RANDOM>'

2

Exchange authorization code for access token

Request:

curl -L \
  --request POST \
  --url '{AUTH_BASE_URL}/realms/users/protocol/openid-connect/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "code": "<YOUR_AUTHORIZATION_CODE>",
    "redirect_uri": "https://<YOUR_APP_CALLBACK_URL>"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "scope": "<REQUESTED_SCOPE_ONE> <REQUESTED_SCOPE_TWO>",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.e...signature"
}

How to make authenticated requests

Include the access token in all API requests:

curl -L \
  --request GET \
  --url '{BASE_URL}/inventory/list' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

For more information about authenticating in Navixy Repository API, see Authentication.

Step 2. Activate your GPS device

GPS devices in Navixy Repository API are called inventory items and are organized into inventories. For a more in-depth explanation of activating a GPS device and working with inventories, see Activating a GPS device.

1

Fetch device model specification

Navixy Repository API supports a wide variety of GPS devices, each with its own unique set of parameters for activation and communication. To work with any GPS device, you first need its specific parameters. You can retrieve the complete profile for any supported model by querying the /inventory_item/master/model/list endpoint.

For example, to get the specifications for a Teltonika FMC234, use the following request:

curl -L \
  --request GET \
  --url "{BASE_URL}/inventory_item/master/model/list?q=Teltonika%20FMC234" \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

From the response, you will need to save the following critical parameters for future requests:

• code: The unique identifier for the model (e.g., telfmc234).

• activation_methods: An array of supported activation methods. Note the id of the method you plan to use (e.g., 1).

• method_fields: A list of fields required for the chosen activation method (e.g., iccid).

{
    "data": [
        {
            "code": "telfmc234",
            "vendor": "Teltonika Telematics",
            "name": "Teltonika FMC234",
            ...,
            "activation_methods": [
                {
                    "id": 1,
                    "title": "SIM card provided with a device",
                    "method_fields": [
                        {
                            "field": "iccid",
                            "title": "ICCID number of SIM-card from the package",
                            "optional": false,
                            "pattern": "89[0-9]{17,18}"
                        }
                    ]
                },
                ...
            ]
        }
    ],
    "has_more": false
}

2

Create an inventory

Next, create an inventory to house your new device. Inventories are logical containers for organizing your items.

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory/create' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "Florida",
    "description": "Florida branch office"
  }'

The API will respond with the new inventory's id. Save it for the next step.

{
  "id": 12
}

3

Create a master device

Devices that can transmit GPS data independently are called master devices. In Navixy Repository API, devices are stored as inventory items.

Now, create a master device as an item in your inventory. You will need inventory_id and the model code you've fetched previously, as well as device_id , which is typically its IMEI (pattern: ^[0-9a-zA-Z\\-]{1,64}$).

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/master/create' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "inventory_id": 12,
    "device_id": "356307042441234",
    "label": "Vessel 001",
    "model": "telfmc234"
  }'

Save the returned device id for the next and final step.

{
  "id": 123
}

4

Activate the device

Finally, activate the device using its id from the previous step along with the activation_method_id and fields you saved earlier.

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/master/activate' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 123,
    "device_id": "356307042441234",
    "model": "telfmc234",
    "activation_method_id": 1,
    "fields": {
      "iccid": "8912345678901234567"
    }
  }'

A successful activation will return a 204 No Content response.

Verification and next steps

Let's confirm everything works by listing your inventory items:

curl -L \
  --request GET \
  --url "{BASE_URL}/inventory_item/master/list" \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

You should see your device in the response.

What you've accomplished:

• Authenticated with the Navixy Repository API

• Fetched the specification for your device model

• Created an inventory for your devices

• Created an inventory item representing your device

• Activated the device that can now transmit location data

Next steps

Now that you have the basics set up, you can:

• Add and activate more devices by creating additional inventory items

• Create new inventories to store your devices

• Create custom asset types for different categories of assets

• Create assets (objects representing real-world business units) and assign devices to them

• Group assets by location, department, or function via asset links