General

Please help us getting better, by sending us feedback and your questions! If you struggle with some details in the implementation or something is unclear, just drop us a line at devs@sensorberg.com.

This documentation is in active development mode and will change frequently.

Authentication

Authentication is taking place with the help of OAuth 2.0 on the API level. So you are able to use the API in the name of a user or an app itself.

OAuth 2

If you need any information about OAuth 2.0, we will extend this documentation. For now, please consult the official resources at oauth.net.

The following information will be provided by us:

  • Access Token URL: $base_url/oauth/token
  • Username: $username
  • Password: $password
  • Client ID: $client_id
  • Client Secret: $client_secret
  • Scope: me, app or basic

$username, $password, $client_id and $client_secret must be stored and transfered only via encrypted transport mechanisms.

In addition to the endpoint mentioned above, we also provide the following OAuth 2.0 related endpoints:

  • $base_url/oauth/authorize - Managing authorization code, following RFC 6749 (Examples: POST, DELETE)
  • $base_url/oauth/token - Managing Access token, following RFC 6749 (Examples: POST, DELETE)
  • $base_url/oauth/revoke - Revoking a token, following RFC 7009 (Example)
  • $base_url/oauth/introspect - OAuth 2.0 Token Introspection, following RFC 7662 (Example)
  • $base_url/oauth/token/info - Shows details about the token used for authentication (Example)

Scopes

  • me - the endpoint requires an user access token
  • app - the endpoint requires an app access token
  • basic - the endpoint requires an app access token with the basic right

Supported grant flows

Please choose your required grant flow wisely and take special care of the user credentials.

For authorising as app role on GraphQL you need to create an OAuth token with the client_credentials grant flow.

For regular users:

  • Using an external OAuth provider (OpenID, Cobot, etc ..)
  • Using Sensorberg web - user and password
  • Writing a token in our database per user (external_authentication_token)

For machine to machine communitcation, please use the app scope with the following parameters:

  • Only using OAuth grant_type user_credentials with client_id and client_secret

Curl example: Getting access token with app scope (machine to machine)

curl --location --request POST 'https://base.sensorberg.com/oauth/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode 'client_id=xxx' \
     --data-urlencode 'client_secret=xxx\
     --data-urlencode 'scope=app'

The response will look similiar to:

{
    "access_token": "...",
    "token_type": "bearer",
    "expires_in": 1209600,
    "refresh_token": "...",
    "scope": "app",
    "created_at": 1520348832
}

Curl example: Login with external authentication token as a normal user

When the oauth_application (API application) has an associated mobile app with Authentication type: external authentication token then user and password should be replaced with external_authentication_token which is the external_authentication_token field for the given user.

curl --location --request POST 'https://base.sensorberg.com/oauth/token?external_authentication_token=token_for_sensorberg&client_id=xxxx&scope=me&grant_type=password'

The response will look similiar to:

{
  "grant_type": 'password',
  "client_id": $client_id,
  "scope": 'me' (or one of the other scopes supported by the app),
  "external_authentication_token": $external_authentication_token
}

Format

Our APIs are following the specifications at jsonapi.org.

Please be aware that you need to send application/vnd.api+json as Content-Type for POST and PUT requests.

Documentation

Each type of API is offering a Swagger based documentation. You can use this documentation during development. A link to the specific documentation can be found at the top of each API documentation.