Human user and device authentication is done by email/password authentication. Any human user can sign up for an netilion account and login after he validated his email address via the automated confirmation email. To authenticate devices and machines so called technical users can be created.
For security reasons, the authentication of human users is only possible via the Netilion ID web application: https://netilion.endress.com/app/id.
As mentioned before, human users can only authenticate themselves via the Netilion ID web application. To allow an application to access the data of a user, the OAuth 2 protocol is used. In detail, this means that an application can request an access token via the Authorization Code Flow to gain access to the data without seeing the user's credentials.
For devices or machines that need to access data in a process where no human interaction is involved, technical users can be used to authenticate and authorize the devices. In OAuth 2 terms this is done via the Password Grant. Access Controls can then be used to define which data a device can access.
The OAuth 2 protocol can easily be implemented in any programming language. To get it running faster you can also use one of many open source libraries which are listed here.
The password grant only works for devices or machines, but not for human users. To access the API the client requests an token using the api key, api secret, username and password. The API returns an access token which is valid for 11 minutes and a refresh token with longer validity time which can be used to refresh the access token. The access token can than be used to access the API resources. If the access is not needed anymore the token must be revoked.
To get access to the API, a connect subscription with API Key of type OAuth and a Technical User is needed. You can create one in the Netilion ID web application under: https://netilion.endress.com/app/id/subscriptions/connect.
To request a token, following request needs to be made against https://api.netilion.endress.com/oauth/token
with the Content-Type application/x-www-form-urlencoded
.
Content-Type: application/x-www-form-urlencoded
client_id=[API KEY]&client_secret=[API SECRET]&grant_type=password&username=[USERNAME]&password=[PASSWORD]
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
client_secret | Your client applications api secret. | |
grant_type | This tells the token endpoint that the application is using the password code grant type. | |
username | The username of the technical user. | |
password | The password of the technical user. |
The response for this request will look like this:
{
"access_token": "fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79",
"token_type": "Bearer",
"expires_in": 660,
"refresh_token": "d2375e356e185a745b1176f952ab7c37e58e95a1fabe715a2d4a2bc5a9e00835",
"created_at": 1593675309
}
The returned access_token
can be used to make further requests by adding following HTTP Header to any request against the API:
Authorization: 'Bearer fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79'
With the returned refresh token, a new access token can be created. The expiration time of the access token is fixed to 11 minutes (it doesn't get extended with every request like normal sessions do), this means the access token must be refreshed when it gets expired.
To refresh a token, following request needs to be made against https://api.netilion.endress.com/oauth/token
with the Content-Type application/x-www-form-urlencoded
:
Content-Type: application/x-www-form-urlencoded
client_id=[API KEY]&client_secret=[API SECRET]&grant_type=refresh_token&refresh_token=[REFRESH TOKEN]
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
client_secret | Your client applications api secret. | |
grant_type | This tells the token endpoint that the application wants to refresh the token. | |
refresh_token | The refresh token. |
The response for this request will look like this:
{
"access_token": "4984907bf742025b93883c6081ff2acb70fa04c485ac95ca88d00ce4addc6a18",
"token_type": "Bearer",
"expires_in": 660,
"refresh_token": "f26a8fa2f25e01c6a1581c354b6ab4008d236ae41e143162f0a91c4baed91ea4",
"created_at": 1593679241
}
If the token is not needed anymore, it can be revoked with following request against https://api.netilion.endress.com/oauth/revoke
with the content type application/x-www-form-urlencoded
and the Authorization
header:
Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'
token=[ACCESS_TOKEN]
Parameter | Description | |
---|---|---|
token | The access token to revoke. |
To get access to the API, a connect subscription with API Key of type OAuth. You can create one in the Netilion ID web application under: https://netilion.endress.com/app/id/subscriptions/connect.
There you can also define the redirect URIs for the authorization process (details will follow below).
Notice: Please contact our support to get your application approved and enabled for the Authorization Code Flow.
This sequence diagram shows the complete process to retrieve a token using the Authorization Code Flow:
To request the authorization code, you need to redirect the users browser to following URL:
https://netilion.endress.com/app/id/sign_in
?response_type=code
&client_id=[API_KEY]
&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback
&state=[STATE]
Parameter | Description | |
---|---|---|
response_type | This tells the authorization server that the application is initiating the authorization code flow. | |
client_id | Your api key | |
redirect_uri | The URL which Netilion ID should redirect to after the sign in of the user (This URI needs to match with one of the redirects URIs defined in your connect subscription) | |
state | The state will be send back as a param with your redirect URI after the user was authenticated. A state is typically a random string which you need to generate. You need to save the state on your end, so you can validate it when handling the callback. This is used to prevent CSRF attacks. |
After the user signed in, the Netilion ID web application will redirect the user back to your application:
https://example.org/callback
?code=[AUTHORIZATION CODE]
&state=[STATE]
Your should now validate the state, by comparing it to the string you stored in the session. If they match, you can request an access token with the given authorization code.
To request a token, the following request needs to be made against https://netilion.endress.com/app/id/oauth/token
with the Content-Type application/x-www-form-urlencoded
:
Content-Type: application/x-www-form-urlencoded
client_id=[API KEY]&client_secret=[API SECRET]&grant_type=authorization_code&code=[AUTHORIZATION CODE]&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
client_secret | Your client applications api secret. | |
grant_type | This tells the token endpoint that the application is using the authorization code grant type. | |
code | The authorization code it was given in the redirect. | |
redirect_uri | The same redirect URI that was used when requesting the code. |
The response for this request will look like this:
{
"access_token": "fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79",
"token_type": "Bearer",
"expires_in": 660,
"refresh_token": "d2375e356e185a745b1176f952ab7c37e58e95a1fabe715a2d4a2bc5a9e00835",
"created_at": 1593675309
}
The returned access_token
can be used to make further requests by adding following HTTP Header to any request against the API:
Authorization: 'Bearer fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79'
With the returned refresh token, a new access token can be created. The expiration time of the access token is fixed to 11 minutes (it doesn't get extended with every request like normal sessions do), this means the access token must be refreshed when it gets expired.
To refresh a token, following request needs to be made against https://netilion.endress.com/app/id/oauth/token
with the Content-Type application/x-www-form-urlencoded
:
Content-Type: application/x-www-form-urlencoded
client_id=[API KEY]&client_secret=[API SECRET]&grant_type=refresh_token&refresh_token=[REFRESH TOKEN]
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
client_secret | Your client applications api secret. | |
grant_type | This tells the token endpoint that the application wants to refresh the token. | |
refresh_token | The refresh token. |
The response for this request will look like this:
{
"access_token": "4984907bf742025b93883c6081ff2acb70fa04c485ac95ca88d00ce4addc6a18",
"token_type": "Bearer",
"expires_in": 660,
"refresh_token": "f26a8fa2f25e01c6a1581c354b6ab4008d236ae41e143162f0a91c4baed91ea4",
"created_at": 1593679241
}
If the token is not needed anymore, it can be revoked with following request against https://netilion.endress.com/app/id/oauth/revoke
with the Content-Type application/x-www-form-urlencoded
and the Authorization
header:
Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'
token=[ACCESS_TOKEN]
Parameter | Description | |
---|---|---|
token | The access token to revoke. |
You can fully implement the authorization process yourself as described here, but we recommend using one of the following libraries (it must be one that supports PKCE):
To get access to the API, a connect subscription with API Key of type OAuth. You can create one in the Netilion ID web application under: https://netilion.endress.com/app/id/subscriptions/connect.
There you can also define the redirect URIs for the authorization process (details will follow below).
Notice: Please contact our support to get your application approved and enabled for the Authorization Code Flow with PKCE.
This sequence diagram shows the complete process to retrieve a token using the Authorization Code Flow:
In order to start the auhtorization process, a so-called "code verifier" must first be created in the app. This is a cryptographically random string of characters A-Z, a-z, 0-9 and the punctuation marks -._~ (hyphen, dot, underscore and tilde), between 43 and 128 characters long.
For the authorization code request, the SHA256 hash of this "code verifier" must be sent as a BASE64-encoded encoded string in the parameter "code_challange".
To request the authorization code, you need to open an in app browser in your app and point it to the following URL:
https://netilion.endress.com/app/id/sign_in
?response_type=code
&client_id=[API_KEY]
&redirect_uri=my-netilion-app%3A%2F%2Foauth%2Fcallback
&code_challenge=[CODE_CHALLANG]
&code_challenge_method=S256
&state=[STATE]
Parameter | Description | |
---|---|---|
response_type | This tells the authorization server that the application is initiating the authorization code flow. | |
client_id | Your api key | |
redirect_uri | The URL which Netilion ID should redirect to after the sign in of the user (This URI needs to match with one of the redirects URIs defined in your connect subscription) | |
state | The state will be send back as a param with your redirect URI after the user was authenticated. A state is typically a random string which you need to generate. You need to save the state on your end, so you can validate it when handling the callback. This is used to prevent CSRF attacks. | |
code_challenge | The BASE64-encoded SHA256 hash of the code verifier. | |
code_challenge_method | The state will be send back as a param with your redirect URI after the user was authenticated. A state is typically a random string which you need to generate. You need to save the state on your end, so you can validate it when handling the callback. This is used to prevent CSRF attacks. |
After the user signed in, the Netilion ID web application will redirect the user back to your application:
my-netilion-app://oauth/callback
?code=[AUTHORIZATION CODE]
&state=[STATE]
Your should now validate the state, by comparing it to the string you stored in the session. If they match, you can request an access token with the given authorization code.
To request a token, the following request needs to be made against https://netilion.endress.com/app/id/oauth/token
with the Content-Type application/x-www-form-urlencoded
:
Content-Type: application/x-www-form-urlencoded
client_id=[API KEY]&grant_type=authorization_code&code=[AUTHORIZATION CODE]&code_verifier=[CODE VERIFIER]&redirect_uri=my-netilion-app%3A%2F%2Foauth%2Fcallback
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
grant_type | This tells the token endpoint that the application is using the authorization code grant type. | |
code | The authorization code it was given in the redirect. | |
code_verifier | The code verifier create on the beginning of the authorization process. | |
redirect_uri | The same redirect URI that was used when requesting the code. |
The response for this request will look like this:
{
"access_token": "fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79",
"token_type": "Bearer",
"expires_in": 660,
"refresh_token": "d2375e356e185a745b1176f952ab7c37e58e95a1fabe715a2d4a2bc5a9e00835",
"created_at": 1593675309
}
The returned access_token
can be used to make further requests by adding following HTTP Header to any request against the API:
Authorization: 'Bearer fe5d8df13913902eac4382da27b74f346e65e6f8acd67a7fa50a6ef0990cda79'
With the returned refresh token, a new access token can be created. The expiration time of the access token is fixed to 11 minutes (it doesn't get extended with every request like normal sessions do), this means the access token must be refreshed when it gets expired.
To refresh a token, following request needs to be made against https://netilion.endress.com/app/id/oauth/token
with the Content-Type application/x-www-form-urlencoded
:
Content-Type: application/x-www-form-urlencoded
client_id=[API KEY]&grant_type=refresh_token&refresh_token=[REFRESH TOKEN]
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
grant_type | This tells the token endpoint that the application wants to refresh the token. | |
refresh_token | The refresh token. |
The response for this request will look like this:
{
"access_token": "4984907bf742025b93883c6081ff2acb70fa04c485ac95ca88d00ce4addc6a18",
"token_type": "Bearer",
"expires_in": 660,
"refresh_token": "f26a8fa2f25e01c6a1581c354b6ab4008d236ae41e143162f0a91c4baed91ea4",
"created_at": 1593679241
}
If the token is not needed anymore, it can be revoked with following request against https://netilion.endress.com/app/id/oauth/revoke
with the Content-Type application/x-www-form-urlencoded
and the Authorization
header:
Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'
client_id=[API KEY]&token=[ACCESS_TOKEN]
Parameter | Description | |
---|---|---|
client_id | Your client applications api key. | |
token | The access token to revoke. |
Users can authorize other users to read, update, delete and/or manage their data. They can create new permissions to a single user or to all users within a user group.
To create this, this endpoint can be used
POST https://netilion.endress.com/v1/permissions
A sample body for this POST request:
{
"permission_type": [
"can_read"
],
"assignable": {
"id": 47392,
"type": "Usergroup"
},
"permitable": {
"id": 4485958,
"type": "Asset"
}
}
permission_type
points to what kind of permission do you want to grant, there are four types:
can_read
: enable user to see the objectcan_update
: enable user to change the object attributes (not necessarily all)can_delete
: enable user to delete the objectcan_permit
: enable user to grant new permissions or delete existing permissions on this objectKeep in mind, these permissions are disjoint from each other, they do not imply anything on each other. There is no hierarchy between the permission types themselves.
assignable
points to whom you want to assign the permission, the following assignable types are available:
User
Usergroup
The given ID, is the ID of the User
or Usergroup
you want to assign the permission to.
permitable
points to which object you want to give the permission, the following permitable types are available:
Asset
Instrumentation
Node
Document
EDM::EdgeDevice
Event
Usergroup
APIKey
ClientApplication
BillOfMaterial
PurchaseOrder
Delivery
Quotation
RequestOfQuotation
Recipe
The given ID, is the ID of the object you want to assign the permission to.
For some objects that are closely related in real life, e.g. Asset and instrumentation/tag. There is an implicit permission inheritance between the models. For example, if the user get the 'update' permission on a certain instrumentation/tag, she/he will get automatically the 'update' permission to all assets that are assigned to this instrumentation/tag. These permissions on these assets will be automatically removed when this relation is removed, e.g. instrumentation/tag is deleted or the asset is not assigned to the instrumentation/tag anymore.
The following graph shows the models that are affected with this inheritance concept:
Keep in mind, that the object can inherit the permission from two different paths, e.g an asset can be under two nodes with read permission to a certain user. If you remove the read permission from one node, the user can still see the asset because of the permission inherited from the other node which still exists.