In the Thing'in API, to perform any kind of requests you need an access token which will hold the rights owned by your user.
To acquire an access token you must first obtain a Basic Authentication Header. You can generate it once and for all using this web interface : https://www.blitter.se/utils/basic-authentication-header-generator/
If you set the username : "user" and password : "password" and then click on the ''Generate Header'' button, you should be given something like this
Authorization: ''Basic dXNlcjpwYXNzd29yZA==''
This, holds in a base 64 encoded format, the credentials data of the user "user", replace the fields with your own login and password.
Once you have made the generation copy everything including "Basic ", it is needed to respect the standard form of Basic OAuth.
Send the following request:
post /auth
header : Authorization : Bearer [Paste your Basic Authentication Header]
Body:
{
"scopes": ["r1","r2"],
"domains": ["d1", "d2"]
}
The fields scopes and domains are optionals, you may have to set their value depending on your user. If your user has only one attributed domain and no scopes, it would look like so :
post /auth
header : Authorization : [Paste your Basic Authentication Header]
Body:
{
"domains": "http://www.mydomain.com"
}
In the response, you should receive in fulltext an encoded Json Web Token.
If you're curious you can go to https://jwt.io, and copy the JWT into the whiteboard name "ENCODED" to see the decoded content of your JWT, you should find "scopes", "domains" and "externalid".
{
"domains": [
"http://www.mydomain.com"
],
"jti": "5044e0d0-9ca6-11e8-89b8-fa163ed0977e",
"sub": "f42121ba-82f9-4404-a848-ab0bcc1f172a",
"exp": 1533996275,
"iat": 1533909875,
"iss": "Thing_in",
"externalid": "user",
"scopes": [
"provider"
],
"kid": "b826a4e5-0ab9-4a9b-8b49-79070e6834bf"
}
A Json Web Token may only be ''active 24 hours before it expires'', you cannot refresh it but you can use this very JWT to generate a brand new one.
post /auth/ak
header : Authorization : Bearer [Your JWT]
Body:
{}
This will return you a newly generated JWT which will in turn expire in 24 hours. This way you can create a chain of JWT to renew your expiration time.
Now that you have a safe way to maintain your JWT alive, all is left is to set the Authorization header with Bearer <Your current JWT> in every requests you send to the Thing'In Api and you're good to go !
The best practice about authentication into Thing'In would be to authenticate yourself once into the system using the /auth entry of the API and to use your current JWT a bit before it expires (once the current JWT has only 1 hour or 10 minutes left) to regenerate a new one with auth/ak.
This may not be the most easy way to implement authentication but to us it is by far the most efficient as it limits the number of authentication request on the network and the number of tokens we have to keep in check before expiration.