Work groups

Introduction

The workgroup entity is employed for the purpose of consolidating users who occupy identical roles within the specified organisation.

API specification

Subsections of Work groups

Work groups relations

Introduction

The workgroup entity enables the consolidation of disparate channels, thereby conferring management permissions upon distinct user roles.

API specification

Geo-clusters

Limited access

This feature is only available to root and super_admin_domain profiles. Ask your administrator for proper user role profiling.

Introduction

A geo-cluster is defined as a grouping of devices belonging to multiple organisations, which are related to work groups.

API specification

Users

Introduction

  • For further details regarding role permissions, please refer to the section on user profiles.

  • For further details regarding the login process in OpenGate, please refer to the user LOG-IN section.

Two-Factor Authentication (2FA)

Two-Factor Authentication (2FA) can be configured at the user level.

The only possible value is “TOTP”. (Time-Based On-Time) as defined in [RFC-6238] (https://www.rfc-editor.org/rfc/rfc6238).

By default, this field will be set to “NONE”. If you wish to deactivate the 2FA, please set the property 2FaType to NONE and perform a PUT on the user.

Please refer to the schema for each attribute used.

Log in with Two-Factor Authentication (2FA)

In the event that two-factor authentication (2FA) has been enabled for a particular user, it is necessary to incorporate the code generated by the associated application into the “2FaCode” attribute of the JSON.

Configure your application

Upon initial login following the configuration of two-factor authentication (2FA), the LOGIN service will respond with a URL location in the headers containing the configuration parameters. These parameters should be used to configure your application to generate the codes.

The URL will be as follows: otpauth://totp/2FA?secret=CAX3VP5O7GWZXUDWQOK4267DGXXSFIDQ&issuer=OpenGate&algorithm=SHA1&digits=6&period=30

Description of the attributes of the URL

  • secret: Contains the secret key to generate codes.
  • period: Defines the time validation period of the code.
  • digits: Defines the length of the generated code.
  • algorithm: Defines the algorithm used to generate the codes.
  • issuer: Defines the subject, the name of the server.

Some applications only require the secret field, while others may need all parameters.

Comprehensive API actions

Reading a user

Please replace {id} with the email address of the user you wish to retrieve. There are two ways to use the GET method:

  1. Administrative: This is the standard use of the GET method as defined in HTTP. In this case, you use GET with the Apikey.
  2. Login: You can use the method GET to log in, adding the password in the field of the header X-ApiPass. The Apikey is not necessary.

Updating a user

An administrator is able to modify another user’s API key or password, update their own API key, or update their own password.

To update the ApiKey or password of another user by an administrator

Any user with administration role is allowed to change the ApiKey / password of any managed user (excluding himself), the same way as any other user’s field.

In this case, the ApiKey or password will be considered as any other basic user data. In this case, it’s allowed to change the ApiKey or password with any other user’s field. If the administrator needs to change his own ApiKey/password, it must be done as explained bellow.

To update your own ApiKey

Any user with an administrative role is permitted to modify the ApiKey/password of any managed user (excluding themselves), in a manner consistent with the process for modifying any other user’s field.

In this instance, the ApiKey or password will be treated in the same way as any other basic user data. It is therefore permitted to change the ApiKey or password with any other user’s field. If the administrator wishes to change their own ApiKey/password, this must be done in accordance with the instructions set out below.

To update your own password

As with updating your own ApiKey, any user is able to change their own password. This is the only method available, regardless of whether the user has an administration profile. In this case, the current user’s password must be included in the X-ApiPass field of the REQUEST HEADERS section (the X-ApiKey field is not required). Additionally, the JSON of the REQUEST BODY should include only the new password as shown in the “Change the user’s own password” option. Please note that it is not permitted to change any other user’s field.

When setting a password…

The password must meet the following criteria for both creating and updating users:

  • It must be between 12 and 25 characters long.
  • It must include upper case letters.
  • It must include lowercase letters.
  • It must include numbers.
  • It must include special characters: !"#$%&’()*+,-./:;<=>?@[]^_`{|}~

The password will have an expiration time of 6 months, by default.

Logging in OpenGate platform.

Note

It is not a requisite to include an API key or JWT token in the header of the request.

The JWT token will be validated by OpenGate under the following conditions:

  1. The JWT token will have an expiration time, typically 24 hours.
  2. The JWT token will be signed with an OpenGate encrypted key. If the token received is not signed with the same encrypted key or has been modified, it will be rejected.

API specification

Subsections of Users

User login

For you are authenticate in OpenGate you have to do LOG-IN to obtain a token JWT or an ApiKey:

Do login

Basic login

Do you need an email and password.

flowchart TD
    CU["CREATE User"] --> V{"Valid User"}
    V -- No --> E400["ERROR 400<br>Json malformed"]
    V -- "Yes, LOG-IN" --> LOGIN["Do LOG-IN<br>email and password"]
    LOGIN --> VC{"Valid<br>email and password"}
    VC -- No --> E401["ERROR 401<br>Bad credentials"]
    VC -- Yes --> OK["Return: 200 OK<br>Return data (JWT and ApiKey)"]

    classDef error fill:#f9d0d0,stroke:#c85a5a,color:#000
    classDef ok fill:#a8ecd0,stroke:#2b9c6e,color:#000
    class E400,E401 error
    class OK ok

Login with Two Factor Authentication

Do you need an email, password and an 2FA Code generated.

How can you generate the 2FA code?

First, you have to configure your application to generate codes.

Configure your application

When you do login in OpenGate, the first time after configuring 2FA, the LOG-IN service responds with an error code 401, but in the headers contains an URL in the attribute location with the parameters of configuration.

You have to use this parameters to configure your application to generate the codes.

The URL of location will be like this otpauth://totp/2FA?secret=CAX3VP5O7GWZXUDWQOK4267DGXXSFIDQ&issuer=OpenGate&algorithm=SHA1&digits=6&period=30

Description of the attributes of the URL:

  • secret: contain the secret key to generate codes.
  • period: define the time of validation of the code.
  • digits: define the length of the code generated.
  • algorithm: define the Algorithm used to generate the codes.
  • issuer: define the subject, the name of the server.

Some applications only need the secret field, and others need all parameters.

You can see the flow of this process in follow diagram:

flowchart TD
    CU["CREATE or UPDATE USER<br>with 2FA"] --> V{"Valid User<br>with 2FA type"}
    V -- No --> E400["ERROR 400<br>Json malformed"]
    V -- "Yes, LOG-IN" --> LOGIN["Do LOG-IN<br>without 2FA Code"]
    LOGIN --> FIRST{"First time"}
    FIRST -- No --> E401A["ERROR 401<br>Bad Credentials<br>or Bad 2Fa Code sent"]
    FIRST -- Yes --> HDR["Return: ERROR 401<br>Headers with URL 2FA"]
    HDR --> APP["With URL - Configure APP"]
    APP --> GEN["Generate 2FA code<br>with the application"]
    GEN --> LOGIN2["Do LOG-IN with 2FA"]
    LOGIN2 --> VC{"Valid<br>email and password"}
    VC -- No --> E401B["ERROR 401<br>Bad Credentials"]
    VC -- Yes --> EXP{"Code expired<br>Code invalid"}
    EXP -- No --> OK["Return 200 OK<br>Return data (JWT and ApiKey)"]
    EXP -- Yes --> E401C["401 ERROR<br>Invalid Code"]

    classDef error fill:#f9d0d0,stroke:#c85a5a,color:#000
    classDef ok fill:#a8ecd0,stroke:#2b9c6e,color:#000
    classDef step fill:#addcf8,stroke:#2b7cb8,color:#000
    class E400,E401A,E401B,E401C,HDR error
    class OK ok
    class LOGIN,APP,GEN,LOGIN2 step

2FA error responses

Every 2FA failure returns 401 Unauthorized, so the error code is what tells the cases apart:

Code Situation Context
0x000065 First login after configuring 2FA. Read the location header to configure your application. 2FA
0x000065 2FA is configured but no code was sent. 2FaCode is null
0x000066 The code sent is invalid or expired. 2FaCode
0x000067 A code was sent but the user has no 2FA configured. Log in without the TOTP code. 2FaCode

An expired password is a different case: it returns 403 with code 0x010063.

User profiles

OpenGate by default incorporates a set of user profiles which is listed below:

New adhoc user profiles can be added to adapt to specific needs.

Profiles

  • root
  • super_admin_domain
  • admin_domain
  • admin
  • advanced
  • viewer

root

Total control for managing all resources in the platform

super_admin_domain

super_admin_domain access to the Provision API

  • Domains (create, update, delete)
  • Subdomains (create and update)
  • Organizations (create, update, delete)
  • Work groups (create, update, delete)
  • Channels (create, update, delete)
  • Users (create, update, delete)
  • Certificates (create, update, delete, download)
  • Data models (create, update, delete)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • APNs (create)
  • Radius Clients (create)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Manufacturers (create, read, update, delete)
  • Models (create, read, update, delete)
  • Datasets (create, read, update, delete)
  • Provision processors (create, read, update, delete)
  • Timeseries (create, read, update, delete)
  • Artificial Intelligence (create, read, update, delete)

super_admin_domain access to the Search API

Full access.

super_admin_domain access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

admin_domain

admin_domain access to the Provision API

  • Domains (create, update, delete)
  • Subdomains (create and update)
  • Organizations (create, update, delete)
  • Work groups (create, update, delete)
  • Channels (create, update, delete)
  • Users (create, update, delete)
  • Certificates (create, update, delete, download)
  • Data models (create, update, delete)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • APNs (create)
  • Radius Clients (create)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Artificial Intelligence (read)

admin_domain access to the Search API

Full access.

admin_domain access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

admin

admin access to the Provision API

  • Work groups (create, update, delete)
  • Channels (create, update, delete)
  • Users (create, update, delete)
  • Certificates (create, update, delete, download)
  • Data models (create, update, delete)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • APNs (create)
  • Radius Clients (create)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Artificial Intelligence (read)

admin access to the Search APIs

Full access.

admin access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

advanced

advanced access to the Provision API

  • Users (update yourself)
  • Certificates (download)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Artificial Intelligence (read)

advanced access to the Search API

Full access.

advanced access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

viewer

viewer access to the Provision API

  • Users (update yourself)
  • Certificates (download)
  • Areas (read)
  • Assets entities (read)
  • Devices entities (read)
  • Subscriptions entities (read)
  • Subscribers entities (read)
  • Tickets (read)
  • Artificial Intelligence (read)

viewer access to the Search API

Full access.

viewer access to the Operation API

  • Jobs (read)
  • Tasks (read)
  • Alarms (read)
  • Rules (read)
  • Bundles (read)
  • Download csv

Software and configuration bundles

Software, firmware, configuration. You can rely on OpenGate to update the software, the firmware, or the configuration files of your remote devices.

The updates can be executed using the operations API, but first of all, OpenGate must know the structure of your update bundles.

The following sections show you how to feed OpenGate with your software, firmware, and configuration files.

Bundle object structure

A bundle is a group of deployment elements you want to deploy in a remote device. A bundle can contain four file types:

  1. SOFTWARE
  2. FIRMWARE
  3. CONFIGURATION
  4. PARAMETERS

See Bundle Object

Bundle management workflow

flowchart TD
    START(("Start")) --> B["POST bundle"]
    B --> DE["POST deployment element<br>to the bundle"]
    DE --> Q{"Should the bundle have<br>more deployment elements?"}
    Q -- Yes --> DE
    Q -- No --> END(("End"))

    classDef step fill:#addcf8,stroke:#2b7cb8,color:#000
    classDef terminal fill:#a8ecd0,stroke:#2b9c6e,color:#000
    class B,DE step
    class START,END terminal

We want to make sure you understand the bundle management workflow, because the update operations will use your bundles.

First of all, you must POST a bundle.

Then you must upload, i.e. POST, as many deployment elements as the bundle should have.

Finally, you must set up the state bundle attribute to ACTIVE.

Deployment element

What is a deployment element? A bundle is formed by deployment elements, each of these elements can have files associated or not, depending on the operation associated with the deployment element. In a bundle, through the deployment elements, you can define different actions that you want to perform in the device, such as installing software, updating it, and more.

The operations allowed for a deployment element are:

  1. Install - With this operation, you are trying to include a new deployment (of any type) in the device.
  2. Uninstall - With this operation, you are trying to uninstall a deployment element in the device.
  3. Upgrade - With this operation, you are trying to change the version of a deployment element.

See the structure of a deployment element object at Deployment Element

Attach deployment elements

In order to attach a deployment element to a bundle in the OpenGate API, you must replace {bundle_name} and {version_name} with the identifiers of the bundle and version you want to attach the deployment element to. Because deployment elements need to be uploaded, this POST request differs from others in the OpenGate API. The request must be encoded according to RFC 1867, “Form-based File Upload in HTML”, which OpenGate can parse to “attach” the deployment element to the bundle.

When creating a deployment element, you have three options for attaching a file:

  1. Filling only the downloadUrl field: In this case, the file will be located at the path provided in the downloadUrl field.

  2. Attaching a file without filling the downloadUrl field: Here, the file is uploaded, and the downloadUrl field is automatically populated with the URL of the OpenGate internal file repository.

  3. Attaching a file and filling the downloadUrl field: This option combines the previous two; the file is uploaded to the default path, and the device downloads the file from the path specified in the downloadUrl field.

Important

You must upload at least one deployment element, or your bundle cannot be activated.

Additionally, there is an optional parameter called FileValidationRequired, which forces the platform to validate the file’s integrity. This parameter is only relevant when a valid validator parameter is passed within the accompanying JSON file.

Note that the deployment element file has a maximum size, which can be configured administratively. By default, this limit is set to 22,020,096 bytes.

For the POST request, you must include either the downloadUrl parameter, the associated file, or both.

Comprehensive API actions

Creating a bundle

There are two different ways for creating a bundle:

  • Step by step creating in the first step the bundle and after that creating the different deployment elements included in the bundle
  • Introducing in the post request a zip file with the complete structure of the bundle.

The zip file will have the next content:

  • A file called “manifest.txt” where the content of the bundle is explained
  • The files that will become deployment elements within the bundle.

Updating a bundle

You must replace {bundle_name} with the identifier of the bundle you want to update and {version_name} with the selected version to be updated.

Note

You cannot update a bundle using the file option available in the create option.

You cannot update all the fields of a bundle. The following fields are allowed:

  • description
  • preaction
  • postaction
  • userNotes
  • active
  • Some fields of the deployments elements
Important

If a bundle has been used in an update operation, you can only update the following fields:

  • description
  • userNotes
  • active

Software, firmware, configuration. You can rely on OpenGate to update the software, the firmware, or the configuration files of your remote devices.

The updates can be executed using the operations API, but first of all, OpenGate must know the structure of your update bundles.

The following sections show you how to feed OpenGate with your software, firmware, and configuration files.

Deleting a bundle

Important

If a bundle has been used in an update operation, it can’t be deleted.

API specification