{"id":74,"date":"2018-07-04T07:30:38","date_gmt":"2018-07-04T07:30:38","guid":{"rendered":"https:\/\/dev.foxtrackr.com\/?page_id=74"},"modified":"2018-07-04T09:03:12","modified_gmt":"2018-07-04T09:03:12","slug":"main-dev-concepts","status":"publish","type":"page","link":"https:\/\/dev.foxtrackr.com\/?page_id=74","title":{"rendered":"Main dev concepts"},"content":{"rendered":"<h6>The API access is restricted for the most of the end points and for using it you need to login and get a JWT token. This Token contains a list of ACL attached to the user account and a list of GROUPS attached to the user account. The following paragraphs will introduce these different concepts.<\/h6>\n<h2>Right Management<\/h2>\n<p>The platform, for each of the endpoint access, requires to have a certain level of authorization. These authorization are bases on ACL. The ACL are cumulative: each of them gives you different rights. The API endpoint documentation is indicating what ACL you need to use it.<\/p>\n<table style=\"border-collapse: collapse; width: 100%;\" border=\"1\">\n<tbody>\n<tr style=\"background-color: #ebe8e8;\">\n<td style=\"width: 200.609px;\"><strong>Role<\/strong><\/td>\n<td style=\"width: 363.609px;\"><strong>Description<\/strong><\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_PENDING_USER<\/td>\n<td style=\"width: 363.609px;\">No authorization associated to this ROLE. It is given to any registered user before being activated. Used for self registration.<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_REGISTERED_USER<\/td>\n<td style=\"width: 363.609px;\">No authorization associated to this ROLE. It is given to any registered user once it has been validated.<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_DEVICE_READ<\/td>\n<td style=\"width: 363.609px;\">This authorization allows to request read operation on the devices associated to your account. This ACL allow to read Positions, Temperature, Batteries&#8230;<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_DEVICE_WRITE<\/td>\n<td style=\"width: 363.609px;\">This authorization allows to request write operation on devices. Write operations are basically orders sent to the devices like Reboot, Reset, On request positioning&#8230;<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_DEVICE_CONFIG<\/td>\n<td style=\"width: 363.609px;\">This authorization allows to request device configuration modification. This allows to change the positioning frequency, change the device behavior.<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_DEVICE_ADMIN<\/td>\n<td style=\"width: 363.609px;\">This authorization allows to add, remove devices, attach device to a Sigfox account, a devicetype&#8230;<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_USER_ADMIN<\/td>\n<td style=\"width: 363.609px;\">This authorization gives your account access to the User management APIs (Add, remove, update&#8230;) You can create new account with rights you already have.<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_GROUP_ADMIN<\/td>\n<td style=\"width: 363.609px;\">This authorization gives your account access to the Group management APIs (Add, remove, update&#8230;) You can create new groups to manage your devices organization, manage alarm and push APIs.<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">ROLE_DEVICE_ALERTING<\/td>\n<td style=\"width: 363.609px;\">This authorization gives your account access to the Alarm management APIs. You can activate alarms and configure alarms report<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 200.609px;\">OTHERS<\/td>\n<td style=\"width: 363.609px;\">Some other ACL are used for internal functions.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>JWT \/ Tokens<\/h2>\n<p>JWTokens is created when you sign\/in for a limited duration. This Token is the key to access all the APIs requiring an authentication. You can fin larger documentation on <a href=\"https:\/\/fr.wikipedia.org\/wiki\/JSON_Web_Token\">JWTokens on wikipedia<\/a>.<\/p>\n<p>The JWT have the following format:<\/p>\n<pre class=\" microlight\">Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0X3VzZXIiLCJyb2xlcyI6WyJST0xFX0RFVklDRV9SRUFEIiwiUk9MRV9ERVZJQ0VfV1JJVEUiLCJST0xFX1JFR0lTVEVSRURfVVNFUiIsIlJPTEVfUEVORElOR19VU0VSIl0sImdyb3VwcyI6WyJmb3h0cmFja3JfdjIiLCJpdF9sYWJvIl0sImV4cCI6MTUzMDg2NDQ5OX0.EOuJnKLnqMsH2PgK9dcHZ7JQNypjni3rOCMjkMp86Kz9yFGo5cxV4xbcHmB-W9XzU_pmmQzh2Fxf6liH7-ClaQ<\/pre>\n<p>This Token has 3 different parts:<\/p>\n<ul>\n<li>A header indicating the format of the JWT and the associated signature algorithm.<\/li>\n<li>A payload containing the authorizations and the token duration<\/li>\n<li>A signature validating the authenticity of the Token<\/li>\n<\/ul>\n<p>The Token is not secret but protected by a signature: it can&#8217;t be modified if you do not have the key used to sign it.<\/p>\n<p>To read the content of the JWT in a human readable way you can copy\/paste your token in a site like: <a href=\"https:\/\/jwt.io\/\">jwt.io<\/a>\u00a0[be careful with such website as you are exposing your JWT, JWT is a key to access you data]<\/p>\n<p>The payload of the JWT is containing information like the following:<\/p>\n<pre>{\r\n   \"sub\": \"test_user\",\r\n   \"roles\": [\r\n      \"ROLE_DEVICE_READ\",\r\n      \"ROLE_DEVICE_WRITE\",\r\n      \"ROLE_REGISTERED_USER\",\r\n      \"ROLE_PENDING_USER\"\r\n    ],\r\n    \"groups\": [\r\n      \"myGroup1\",\r\n      \"myGroup2\"\r\n    ],\r\n    \"exp\": 1530864499\r\n}<\/pre>\n<p>You can see the user <strong>login<\/strong> identified as &#8220;sub&#8221;. The different <strong>roles<\/strong> associated to this user, the list of <strong>groups<\/strong> associated to this users. And the <strong>expiration<\/strong> date for this token (time in seconds since EPOC, UTC).<\/p>\n<p>As a JWT token is expiring its validity need to be verified and it needs to be renewed (by login again) before its expiration. The default duration is 2 days. Some specific account have longer expiration.<\/p>\n<h2>Group management<\/h2>\n<p>A group is a way to manage a group of devices. A device can be assigned to multiple groups. Here are the different usage of groups:<\/p>\n<h5>Organize your device:<\/h5>\n<p>You can group device by usage, geography&#8230; into different groups. That way in the web UI you can group devices that way to quickly find one device on many.<\/p>\n<h5>Manage User right access:<\/h5>\n<p>With groups, you can restrict device access for different users. When creating a user you associate it with different groups. So you can have a global view of your devices given to a certain group associated with central users and a branch view containing only a sub list of devices associated to another group associated to local users.<\/p>\n<h5>Manage Alerts<\/h5>\n<p>For each of the group you can select the alarm you want to activate and the way you want to use to propagate it. An alarm can be registered in the backend, pushed over email, sms or webhook for an IFTTT use (or anything else).<\/p>\n<h5>Manage Push API<\/h5>\n<p>To activate the push API your configure the backend URL and\/or activate MQTT settings as part of a group parameters. All the incoming messages from devices attached to a group will trigger one or more HTTP push or MQTT.<\/p>\n<h2>Access to advanced rights<\/h2>\n<p>The default right given when getting an account does not gives you a full access to\u00a0 the APIs. You usually have ROLE_DEVICE_READ and ROLE_DEVICE_WRITE only. For getting larger access, please use the <a href=\"https:\/\/dev.foxtrackr.com\/?page_id=84\">contact form<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The API access is restricted for the most of the end points and for using it you need to login and get a JWT token. This Token contains a list of ACL attached to the user account and a list of GROUPS attached to the user account. The following paragraphs will introduce these different concepts. &hellip; <\/p>\n<p class=\"link-more\"><a href=\"https:\/\/dev.foxtrackr.com\/?page_id=74\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &#8220;Main dev concepts&#8221;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-74","page","type-page","status-publish","hentry"],"jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/P9HKNr-1c","jetpack_likes_enabled":true,"jetpack-related-posts":[{"id":54,"url":"https:\/\/dev.foxtrackr.com\/?page_id=54","url_meta":{"origin":74,"position":0},"title":"Getting Started With API","author":"foxtrackr","date":"July 1, 2018","format":false,"excerpt":"That's your first steps with Foxtrackr for developing your own integration based on our API. This page will help you finding the right way for getting start with the Foxtrackr API. Different Type of integration There are two different ways to integrate with Foxtrackr: The PULL api : In this\u2026","rel":"","context":"Similar post","block_context":{"text":"Similar post","link":""},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/dev.foxtrackr.com\/wp-content\/uploads\/2018\/07\/Foxtrackr_pull_API2.png?resize=350%2C200&ssl=1","width":350,"height":200},"classes":[]}],"_links":{"self":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/pages\/74","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=74"}],"version-history":[{"count":7,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/pages\/74\/revisions"}],"predecessor-version":[{"id":88,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/pages\/74\/revisions\/88"}],"wp:attachment":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=74"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}