{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"2ad69b9a-a922-4ef8-816f-739c91cbaf19","name":"Innotech Omni V3.3 REST API","description":"# Welcome\n\nThis is Innotech Omni REST API that provides an open API to Omni controllers.\n![Omni image](https://imgur.com/ege0YoD.png)\n\nTo use this API you will need to make HTTP requests to your controller IP address over an SSL connection, i.e. `https://controller_IP_address/api`.\n\nAuthorisation is provided using OAuth 2.0 protocol. Once user authentication and authorisation are completed, an access token will be generated. The user can then include this token in their HTTP request header to gain access to various API resource endpoints.\n\n## Authentication\n\nOnly users in the **_Settings > Address Book_** on the web application will have valid authentication credentials. These credentials are the same as used in logging in the web application.\n\n![userInAddressBook](https://imgur.com/amzxTeo.png)\n\nAlso, to provide an extra layer of password protection, the Omni API authorisation server expects user credentials to be hashed with **_SHA-256_** algorithm from the client side. In other words, API users must hash their credentials with SHA-256 **_before_** sending them away for authentication.\n\nOnce a user is successfully authenticated, they will receive an access token in the form of a **JSON Web Token** (JWT). This token must be included in every HTTP request header to successfully make calls to the designated API endpoints.\n\n**_View sample access token in [jwt.ms](https://jwt.ms#access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ikk1VU5ReUpcL2ZxQ3oxV2ZWK2djPSJ9.eyJpc3MiOjAsInN1YiI6Im05Zk1rdHk1b0dcL0RMYzZPNGtsdnFJbFk3Zz09IiwiYXVkIjoiODdjZjg0NTQtYzkyZi00NjI0LTliM2ItM2UzNzdmZTc3NjNhIiwibmJmIjoxNTgyNzY4Mjc5LCJpYXQiOjE1ODI3NjgyNzksImV4cCI6MTU4MjgxMTQ3OX0.lLqOqUAyGi7NfN8RoctBH8QXOljDZq3KSDaFE1nITU3zcP_HN1xVSfv5rAjh2p4e36JsxjftCQBrh4WVODnfvJmQe9HPIlM3Des5J9X65uk5G9CLDSTYfci0xp-sCMIPL2x469mNUoN1EOyjSOfV2lMH6tUZiXAMMm263x41oPfsUDlOY20HMt6JnzCz8EzyUxPWM3RNj4lfw_crKGbb_YQCc3MOAmAc1YM3CMSDosJUD4BQflVFUm6A9mMXo-dr4m09NEYytIvt6MxE7FOCzty8Pxfu8xLDGqw1IhFq2h2Ff9RP0RfuP5wv_6QfREIXb_XGbIzopVrpND1MGYqQbg)_**\n\n## Authorisation\n\nEach user will only have access to API endpoints matching their access privileges specified in the **_Settings > Access Levels_** page on the web application. For example, if a user only has _View_ access to the _Watches_ page on the web application and _None_ access to the _Schedules_ page, they will not be able to make successful PUT requests to the _Watches API_ or any requests to the _Schedules API_.\n\n![userAllAccessLevels](https://imgur.com/BxJnwge.png)\n\n# Requirements\n\nAn Innotech Omni BEMS Controller is required to provide the API server. Also, for a [Quick Start](#quick-start-with-postman), [Postman](https://www.getpostman.com/) is recommended. [Postman](https://www.getpostman.com/) is a powerful collaboration platform for API development, exploration and testing.\n\n# Configuration\n\n## Omni Web Application\n\n1. Go to `Settings` > `Remote Access` > `Data Sharing`\n2. Under `REST API` section, enable `REST API`\n3. `Token Expiry` can be disabled or enabled. If it is disabled, the access token will not expire. If it is enabled, a number of hours must then be set as the token lifetime, meaning the access token will expire after this amount.\n\n   ![webRestApiSettings](https://imgur.com/3WNmSBM.png)\n\n## Postman\n\nThis configuration is only applicable if you have [Postman](https://www.getpostman.com) installed.\n\n### Turn off SSL certificate verification\n\nFor quick testing, you can turn off Postman's SSL certificate verification to avoid an error of self-signed certificate provided by Innotech that may show up when making HTTP requests to API endpoints.\n\n1. Go to `File` > `Settings`\n2. In the Settings dialog, go to `General` tab > `Request` section\n3. Turn off `SSL certificate verification`\n\n   ![PostmanDisableSSL](https://imgur.com/I6N9err.png)\n\n# Quick Start with Postman\n\nClick on ![runInPostman](https://imgur.com/s4cikau.png) button at the top right corner of this documentation to import all API endpoint collections directly into your Postman application. You will be prompted to install [Postman](https://www.getpostman.com/) if you have not done so.\n\n## 1. Set default variables\n\nSince an Omni Controller will be providing API endpoints, its URL (IP Address) will be the URL for accessing API server. Your credentials including username and password also need to be set in [Postman](https://www.getpostman.com/).\n\nThese values can be set as [collection variables](https://learning.postman.com/docs/sending-requests/variables/) and reused across requests.\n\n_For more information on working with variables and environments in Postman, see [Variables and Environments](https://learning.postman.com/docs/postman/variables-and-environments/variables/)_\n\n1. Under `Innotech Omni REST API` collection on the left hand side, click the Ellipsis icon ![ellipsisIcon](https://imgur.com/mMC6ePm.png) to open the collection options menu.\n2. Click `Edit` to open `Innotech Omni V3.3 REST API` editing tab.\n\n   ![editCollectionButton](https://imgur.com/ve9Pajf.png)\n\n3. Under `Variables` sub-tab is a table with preset variables. Set their values under `Current Value` column.\n\n- `API_URL`: Your controller's IP address\n- `username`: Your username\n- `rawPassword`: Your password, normally used to log in Omni Web App.\n- `hashedPassword`: Leave it as is. When you make a request for an access token, the default current placeholder of `your_hashed_password` will be automatically replaced with a real hash of your password, by an embedded helper script. This hash is used in the authentication process.\n\n4. Click `Save`\n\n   ![setDefaultVars](https://imgur.com/tmMntpz.png)\n\n## 2. Authentication\n\n1. In [Postman](https://www.getpostman.com), to the left are imported collections under `Innotech Omni V3.3 REST API`, ready for Omni API testing. Navigate to `Authentication` > `Token` > `POST Get access token` request.\n\n   ![getAccessToken](https://imgur.com/6jfLBDL.png)\n\n2. Click `Send` ![sendButton](https://imgur.com/0wZvsao.png).\n3. Once the request is completed, in the response body, an _access token_ is returned. This token is automatically set as a global variable and attached as headers in all other API calls.\n\n   ![tokenReceivedPostman](https://imgur.com/USII5iu.png)\n\n## 3. Make API calls\n\nAll API endpoints are now ready to be called. For example, navigate to `Device Info` > `Device` > `GET List Devices`, and follow the instruction in GET LINK to get information about the primary Omni device and its connected REMs.\n\n# Innotech Support\n\n[Innotech](https://innotech.com/) provides technical support to assist you in using our API services.\n\nYou can view full [API documentation](https://documenter.getpostman.com/view/10295427/TWDdkuAe) or contact us at\n\n- **Website**: https://innotech.com\n- **Email**: sales@innotech.com\n- **Phone**: +61 7 3421 9100\n- **Mail**: **_Innotech Control Systems_**, P.O. Box 292, Sunnybank, QLD 4109, Australia\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"10295427","team":1620452,"collectionId":"2ad69b9a-a922-4ef8-816f-739c91cbaf19","publishedId":"TWDdkuAe","public":true,"publicUrl":"https://documenter-api.postman.tech/view/10295427/TWDdkuAe","privateUrl":"https://go.postman.co/documentation/10295427-2ad69b9a-a922-4ef8-816f-739c91cbaf19","customColor":{"top-bar":"FFFFFF","right-sidebar":"0057B8","highlight":"0057B8"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2021-03-02T00:13:57.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/f329af1a8b1c62b7169c0b2cdb00861b77e58b6f38677ada03afc126036167b0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TWDdkuAe"}