Skip to main content
Version: Torizon OS 6.x.y

Torizon Cloud API (Beta)

Introduction​

This article guides you on automating, extending and integrating the Torizon Cloud features through its REST API. It also brings information about enabling, testing and using the API in our solution.

If you are looking for reference documentation, check our OpenAPI Specification.

Why Use the Torizon Cloud API​

A REST API (Application Programming Interface) is a set of rules and protocols that allows different software applications to exchange resources with each other over the internet. The Torizon Cloud API defines the methods, data formats, and authentication mechanisms that enable your application to request and receive data or perform actions from Torizon Cloud using HTTP requests.

While we provide a comprehensive feature set in our Torizon Cloud Web UI, you can automate, extend and integrate its features in your solution using Torizon Cloud API.

  • Automate: most of the tasks executed on the Torizon Cloud Web UI can be automated and incorporated into any workflow of your product development/maintenance environment, eliminating the need for manual intervention on the web platform.
  • Extend: if you need features not provided in the Web UI platform, you can try implementing them by leveraging the API: filtering information for exhibition according to your product particularities or even conditional updates.
  • Integrate: you can use the API to bring features such as updates, package management and device monitoring to your application or Web UI, giving your own users access to the powerful capabilities of the Torizon Cloud.

Common use cases:

  • Fleet Management: integrate the Torizon Cloud features into your existing fleet management platform to have rich insights on the devices, such as installed software packages and device metrics.
  • Domain translation: you can use the expertise of your support team to manage your devices without having to learn Torizon Cloud namings and UI, incorporating its features in your support platform.
  • CI/CD Workflows: automate the deployment process and integrate it with the build of your application and OS images. While Torizon provides resources for easy automation of OS and application builds with TorizonCore Builder and Docker Containers, these artifacts can be easily deployed across multiple fleets using Torizon Cloud API.

Torizon Cloud API Features​

Product Features​

Most of the features available in the Web UI are accessible using the API:

The Torizon Cloud Web UI is the standard platform to manage your account, repositories and connected applications.

Accounts & Sandbox​

Due to security reasons, it is recommended that you set up a sandbox environment for evaluation and development. You can do this by creating different accounts for sandbox and production. Check our commercial plans to understand services and trial period.

Documentation​

You can learn the API specifications on our Reference Documentation .

To download the OpenAPI specification file, click ./torizon-openapi.yaml:

Download OpenAPI File

Endpoints​

For precise and complete information, check the Reference Documentation.

Check below a summary of useful functionalities available through the endpoints:

Devices

Fleets

Packages

Updates

Metrics

How to Use Torizon Cloud API​

Preparation​

Get an account on https://app.torizon.io with access to the feature. Check the commercial plans for more information.

1. Create an API Client​

1.1. Enter your Torizon Cloud account. On the API Client Manager section, click Create API Client:

Create API Client

1.2. Give the API Client a name and a description. Select the API V2 (beta) Client Type:

Name and Type

1.3. Click or select the Client Secret field to copy and use it during your testing and integration procedures. Note that you won't be able to see the secret after closing the form:

Copy Secret

2. Check the API Endpoints​

There are several ways for you to evaluate Torizon Cloud API:

  • Curl calls: Command-line tool to transfer data between machines using one of many supported protocols (in this case HTTP is relevant). You can easily test the API with curl commands in a Linux terminal.
  • Restish: CLI for interacting with REST-ish HTTP APIs given an OpenAPI Spec. You can use it to automatically generate commands inside Linux Terminal for direct calls to the API endpoints.
  • Postman: Tool to help design, build, test and iterate REST APIs. It allows importing OpenAPI documentation to easily test endpoints.
  • From the application: Using HTTP utilities from your programming language libraries.
  • OpenAPI Generator: Tool that allows the generation of API client libraries (SDK generation), server stubs, documentation, and configuration automatically given an OpenAPI Spec.

The simplest way to check the API endpoint is using our Online Documentation

2.1. Access the authorization form:

Using API Key

2.2. Enter a valid token to get authorization for the API requests. Refer to the Authentication section to learn how to obtain the token:

Entering Credentials or Key

2.3. Execute calls to the API to get examples of the requests.

Try it Out

Execute

3. Integrate Into Your Solution​

Having understood and designed your integration workflow, you can proceed to add calls to Torizon Cloud API in your solution. Remember, you can use the libraries available from the programming language your project uses and even leverage the SDK generated by tools such as OpenAPI Generator, as mentioned above.

There are important aspects you should evaluate when integrating Torizon Cloud API into your solution:

  • API Documentation: Understand and comply with request and response formats, authentication requirements, and any other relevant details of the available endpoints.
  • Rate Limits and Throttling: proper handling of your end users will prevent excessive requests to Torizon Cloud API and potential service disruptions.
  • Versioning and Upgrades: Understand that this API is versioned and consider the impact of future upgrades on your integration.
  • Scalability and Performance: Consider factors such as response times, concurrency, and data volume to ensure Torizon Cloud fulfill your requirements under different usage scenarios.
  • Data Validation and Formatting: Pay attention to data formats, units of measurement, and any specific constraints specified in the API documentation.
  • Error Handling: properly handling error codes, error messages, and fallback options will help provide a robust end-user experience.

Authentication and Security​

Torizon Cloud API uses OAuth2 - Client Credential flow. This means you need a token to successfully execute requests to the API.

Get a Token​

Using your Client ID and Secret you can obtain a valid token to execute requests for the API.

Token URL: https://kc.torizon.io/auth/realms/ota-users/protocol/openid-connect/token

This is a request example using curl to get the token:

$ curl -X POST \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=client_credentials&client_id=<yourClientId>&client_secret=<yourClientSecret>" \
   https://kc.torizon.io/auth/realms/ota-users/protocol/openid-connect/token

Make sure you follow best practices for securely storing credentials. Anyone with access to these credentials can send malicious software to all devices in the repository.

Manage Tokens​

Define the token lifetime during the creation of the API Client, according to your use case requirements. For instance, in CI/CD environments you should generate the token just before the API calls, using the securely stored keys. After the pipeline is completed, you don't need the token, so it can have a short lifetime.

Setting the Lifetime

If needed, delete a Client on the Torizon Cloud Web UI, under the section My Account > API Client Manager. This will immediately invalidate all the tokens generated with this Client:

Deleting Keys

CI/CD​

Torizon IDE Extension brings built-in actions that use the Torizon Cloud API to deploy your OS and application packages to devices or fleets. The provided templates already come with a JSON schema for speeding up the configuration of your GitLab and GitHub CI environment. You can use this as an example to implement automation on other CI/CD environments.

When you create a project using one of the Templates, the Torizon IDE extension creates the configuration files for GitHub and GitLab. If you want to learn how to implement a CI/CD workflow, see CI/CD - Configure Projects to Run CI Pipelines.

Standards & Architecture​

REST​

While REST is not a standard or protocol, it is an important set of architectural constraints that are followed by modern APIs. Being a widely adopted architecture, it allows for easy understanding and fast integration. Torizon Cloud API is implemented as a REST-like API, which means that the main constraints from REST architecture are followed.

OpenAPI​

As defined on OpenAPI Website:

The OpenAPI Specification is a specification language for HTTP APIs that provides a standardized means to define your API to others. You can quickly discover how an API works, configure infrastructure, generate client code, and create test cases for your APIs.

Torizon Cloud API complies with OpenAPI specifications, also contributing to its easy and fast integration capabilities.



Send Feedback!