SERVER API

This section describes the basic messages that provide Thinger.io Server API to interact with its backend functionalities.
Thinger.io API
​New API documentation is available on Swagger! Can be checked out at this link​
All the examples described in this documentation defines URL endpoints based on a relative path, assuming the host is just your server IP, domain, or just the default Thinger.io server. For all calls issued over the default Thinger.io cloud, the host address will be the following:
https://api.thinger.io
Notice that if you are running the Thinger.io server in your own host or domain, a secure HTTPS request may fail if you do not configure the appropriate SSL certificate. You can also use non-secure HTTP for your calls, but it is not recommended in production environments.
Authentication API
REST API Authentication
All queries done to the API Rest interface must be signed in order to access the user resources. So, all request must include an Authorization header that includes the access token to the account:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODYwNDkxNTcsImlhdCI6MTQ4NjA0MTk1NywidXNyIjoianQifQ.pkyG43xiEhDtUHLxuycYv156FGuvNh6nDKQ07kGcaGk
The access token is a JWT Token that needs to be obtained from the user credentials, from a refresh token, or just a from a user-defined access token. So there are two different concepts:
Access Token
Is the token used for granting access to API requests. It should be included in the HTTP Authorization header along with the keyword Bearer. It can be also included as a URL parameter in the HTTP request, with the key authorization (case-sensitive), and the token as the value.
Notice that when this token is obtained from user credentials, or from a refresh token, it has a validity of 2 hours. So it must be refreshed periodically in order have a valid access token.
Refresh Token
The refresh token is a token that cannot provide access to the user resources, but can be used for getting fresh access token in case they expired.
This token, obtained with the user credentials, or with a valid refresh token, has a validity of around 2 months from issue date, and will be refreshed every time you use it for getting a new pair of access, and refresh tokens.
So, the idea behind the authentication is that you need to use the user credentials for getting both an access token and a refresh token. You can keep the refresh token in a secure place, and use the access token for accessing user resources. Once the access token has been expired, then use the refresh token for getting a new access token and a new refresh token.
This way, if the account is used periodically, the user credentials are not required for the authentication process. If the access token is leaked in some way, then the attacker would have a short timespan of access. If the refresh token is also leaked, it can be revoked manually to avoid its use for getting new tokens.
User Token
The tokens defined by the user in their account, can be used just like any other access token to authenticate the request. However, as contrary as the tokens obtained from the user credentials, this token does not expire by default, and the user can define the access level over the account resources. So, in this way, the user could define a token for accessing a single device, or for writing to a data bucket without comprising other account resources.
This kind of tokens can be defined directly from the Thinger.io Console in the Access Tokens section. The following picture illustrates how to add permissions to the token for writing to a single bucket, but you can configure them for granting access to different resources and actions of your account.
Getting Tokens From User Credentials
This method allows getting both the access token and refresh token from the user credentials. It should be used the first time the user logs into the application.
URL
  /oauth/token
Method:
  POST
Content Type
Content-Type:application/x-www-form-urlencoded
Body
  grant_type=password&username=username&password=password
Success Response:
Code: 200
Content:
{  
   "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODYwNDgzNzcsImlhdCI6MTQ4NjA0MTE3NywidXNyIjoianQifQ.A-Vh715P6GjFDBkbh6TmNGxiHWl0KjbDq8tM4qsmTaI",
   "expires_in":7200,
   "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTEzMTE1NzcsImlhdCI6MTQ4NjA0MTE3NywianRpIjoiNTg5MzMwNTkzOWNiZWY0YWEzMDE1YWJiIn0.5Voenem4D90zPNqiS1oVBfguDzygwNzgmcmEi-4N-8Q",
   "scope":null,
   "token_type":"bearer"
}
Error Response:
Code: 401 Unauthorized
Content: 
 {  
    "error":{  
       "message":"invalid username or password"
    }
 }
Getting Tokens With Refresh Token
This method allows getting fresh access token and refresh token from a valid refresh token. It should be called every time the access token has been expired or the refresh token is likely to expire.
URL
  /oauth/token
Method:
  POST
Content Type
Content-Type:application/x-www-form-urlencoded
Body
  grant_type=refresh_token&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTEzMTIzNTcsImlhdCI6MTQ4NjA0MTk1NywianRpIjoiNTg5MzMzNjUzOWNiZWY0YWEzMDE1YWJjIn0.BYwRii9eL7jeQQQqMbuBEZAvwmmVRAU8kWYCNZEDn0s
Success Response:
Code: 200
Content: 
{  
   "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODYwNTY0MjYsImlhdCI6MTQ4NjA0OTIyNiwidXNyIjoianQifQ.H7G4N3MMHxUO2gPHzG0a9N1lZ5--Gt56CC4HOiFMKLE",
   "expires_in":7200,
   "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTEzMTk2MjYsImlhdCI6MTQ4NjA0OTIyNiwianRpIjoiNTg5MzMzNjUzOWNiZWY0YWEzMDE1YWJjIn0.dqxbZegv4oemeDK6czDzQLRfA3da6NShBcseNLTn33Q",
   "scope":null,
   "token_type":"bearer"
}
Error Response:
Code: 401 Unauthorized
Content: 
 {  
    "error":{  
       "message":"invalid refresh token"
    }
 }
Detecting Access Token Expire
The access token expires in around 2 hours from its issue date. There are two ways to determine if the access token has been expired in order to request a new one.
Checking the JWT contents
The first way of checking if an access token is expired, is by parsing the JWT and decoding the payload data. An access token will have a payload like the following:
{
  "exp": 1486048377,
  "iat": 1486041177,
  "usr": "alvarolb"
}
The exp field is the unix timestamp in seconds (UTC) when the token will expire. If your request is after this timestamp, then, the request will fail.
Checking server response
It is possible to check the validity of an access token simply by trying to access any user resource. If the access token is expired, then the authentication will fail, and the API Request query will return a 401 Unautorized.
​
On-Premise
Next - Server
CHANGELOG
Last modified 10mo ago