API Authentication

Authentication for human users

As human user you can simply sign up for an Netilion account, validate your email address and log in. For reasons of security the authentication of human users is always done through Netilion ID web application.

To authenticate your own application a technical user is required. Create a technical user on Netilion ID where you setup your connect subscription.

Authorization

Applications need to be authorized by the OAuth 2 protocol to access to the users’ data: The application requests 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.

Requirements

To access the Netilion API you need a connect subscription with a API Key of type OAuth and a technical user. See in the connect subscription section how to set this up first.

Password grant

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.

Request token

To request a token, the following POST request needs to be made against
https://api.netilion.endress.com/oauth/token. The must be Content-Type application/x-www-form-urlencoded and the parameters are sent url encoded in the body as below:

POST /oauth/token HTTP/1.1
Host: api.netilion.endress.com
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`	Your applications’ password code grant type
`username`	Your technical users’ username
`password`	Your technical users’ password

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 currently fixed to 11 minutes and can be read out from the expires_in attribute in the response. It doesn’t get extended with every request like a user sessions, this means the access token must be refreshed when it gets expired.

Refresh token

The refresh token is valid for a maximum of 24 hours, unless the access token is revoked beforehand.

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:

POST /oauth/token HTTP/1.1
Host: api.netilion.endress.com
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 indicates to 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
}

Revoke token

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:

POST /oauth/revoke HTTP/1.1
Host: api.netilion.endress.com
Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'

token=[ACCESS_TOKEN]

Parameter	Description
`token`	The access token to revoke.

Auth Flow for Web Applications

Requirements

To access the Netilion API you need a connect subscription with a API Key of type OAuth and a technical user.
See in the connect subscription section how to set this up first.

Notice: Please contact our support to get your application approved and enabled for the Authorization Code Flow.

Authorization Flow

This sequence diagram shows the complete process to retrieve a token using the Authorization Code Flow.

Authorization Code Flow

Request authorization code

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 indicates to 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.

Request token

To request a token, the following post request needs to be made against https://netilion.endress.com/app/id/oauth/token. The Content-Type must be application/x-www-form-urlencoded and the parameters url-encoded in the body:

POST /app/id/oauth/token HTTP/1.1
Host: netilion.endress.com
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 indicates to 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'

Refresh token

The refresh token is valid for a maximum of 24 hours, unless the access token is revoked beforehand.

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:

POST /app/id/oauth/token HTTP/1.1
Host: netilion.endress.com
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
}

Revoke token

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:

POST /app/id/oauth/revoke HTTP/1.1
Host: netilion.endress.com
Content-Type: application/x-www-form-urlencoded
Authorization: 'Bearer [ACCESS TOKEN]'

token=[ACCESS_TOKEN]

Parameter	Description
`token`	The access token to revoke.

Auth flow with PKCE for mobile applications

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):

iOS: https://github.com/openid/AppAuth-iOS
Android: https://github.com/openid/AppAuth-Android
React Native: https://github.com/FormidableLabs/react-native-app-auth

Requirements

To access the Netilion API you need a connect subscription with an API Key of type OAuth and a technical user.
See in the connect subscription section how to set this up first.

Notice: Please contact our support to get your application approved and enabled for the Authorization Code Flow with PKCE.

Authorization flow

This sequence diagram shows the complete process to retrieve a token using the Authorization Code Flow.

Authorization Code Flow

### Request Authorization code

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 inicates to 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 code 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.

Request token

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:

POST /app/id/oauth/token HTTP/1.1
Host: netilion.endress.com
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 indicates to 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'

Refresh token

The refresh token is valid for a maximum of 24 hours, unless the access token is revoked beforehand.

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:

POST /app/id/oauth/token HTTP/1.1
Host: netilion.endress.com
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 indicates 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
}

Revoke token

POST /app/id/oauth/revoke HTTP/1.1
Host: netilion.endress.com
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.