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.
Right Management
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.
| Role | Description |
| ROLE_PENDING_USER | No authorization associated to this ROLE. It is given to any registered user before being activated. Used for self registration. |
| ROLE_REGISTERED_USER | No authorization associated to this ROLE. It is given to any registered user once it has been validated. |
| ROLE_DEVICE_READ | This authorization allows to request read operation on the devices associated to your account. This ACL allow to read Positions, Temperature, Batteries… |
| ROLE_DEVICE_WRITE | This authorization allows to request write operation on devices. Write operations are basically orders sent to the devices like Reboot, Reset, On request positioning… |
| ROLE_DEVICE_CONFIG | This authorization allows to request device configuration modification. This allows to change the positioning frequency, change the device behavior. |
| ROLE_DEVICE_ADMIN | This authorization allows to add, remove devices, attach device to a Sigfox account, a devicetype… |
| ROLE_USER_ADMIN | This authorization gives your account access to the User management APIs (Add, remove, update…) You can create new account with rights you already have. |
| ROLE_GROUP_ADMIN | This authorization gives your account access to the Group management APIs (Add, remove, update…) You can create new groups to manage your devices organization, manage alarm and push APIs. |
| ROLE_DEVICE_ALERTING | This authorization gives your account access to the Alarm management APIs. You can activate alarms and configure alarms report |
| OTHERS | Some other ACL are used for internal functions. |
JWT / Tokens
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 JWTokens on wikipedia.
The JWT have the following format:
Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0X3VzZXIiLCJyb2xlcyI6WyJST0xFX0RFVklDRV9SRUFEIiwiUk9MRV9ERVZJQ0VfV1JJVEUiLCJST0xFX1JFR0lTVEVSRURfVVNFUiIsIlJPTEVfUEVORElOR19VU0VSIl0sImdyb3VwcyI6WyJmb3h0cmFja3JfdjIiLCJpdF9sYWJvIl0sImV4cCI6MTUzMDg2NDQ5OX0.EOuJnKLnqMsH2PgK9dcHZ7JQNypjni3rOCMjkMp86Kz9yFGo5cxV4xbcHmB-W9XzU_pmmQzh2Fxf6liH7-ClaQ
This Token has 3 different parts:
- A header indicating the format of the JWT and the associated signature algorithm.
- A payload containing the authorizations and the token duration
- A signature validating the authenticity of the Token
The Token is not secret but protected by a signature: it can’t be modified if you do not have the key used to sign it.
To read the content of the JWT in a human readable way you can copy/paste your token in a site like: jwt.io [be careful with such website as you are exposing your JWT, JWT is a key to access you data]
The payload of the JWT is containing information like the following:
{
"sub": "test_user",
"roles": [
"ROLE_DEVICE_READ",
"ROLE_DEVICE_WRITE",
"ROLE_REGISTERED_USER",
"ROLE_PENDING_USER"
],
"groups": [
"myGroup1",
"myGroup2"
],
"exp": 1530864499
}
You can see the user login identified as “sub”. The different roles associated to this user, the list of groups associated to this users. And the expiration date for this token (time in seconds since EPOC, UTC).
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.
Group management
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:
Organize your device:
You can group device by usage, geography… into different groups. That way in the web UI you can group devices that way to quickly find one device on many.
Manage User right access:
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.
Manage Alerts
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).
Manage Push API
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.
Access to advanced rights
The default right given when getting an account does not gives you a full access to the APIs. You usually have ROLE_DEVICE_READ and ROLE_DEVICE_WRITE only. For getting larger access, please use the contact form.