Let's get you started!

API Key

For every call we demand a subscription key in the header. This can be found under your profile if you have subscriptions. These subscriptions can be requested under products

Authentication

The OAuth2 authorization code flow should be used to integrate web application. More information about this flow can be found over here: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2#grant-type-authorization-code

Flow

  1. In order to login: the user needs to navigate to the following url at the securex broker:
    https://logon.securexacc.eu/adfs/oauth2/authorize/

    ?client_id=[clientid]

    &resource=[clientid]

    &redirect_uri=[redirect_uri]

    &response_type=code

    &scope=openid

    &response_mode=query

  2. The user logs in at the identity broker and gets redirected to your client application

  3. Your client application extract the authorization code from the url and sends it to its own backend

  4. The client application exchanges the authorization code for an access token using a server to server to call (There is no refresh token available yet)

    • The access token itself is a JWT token. The JWT token can then be decoded. You can test this at https://jwt.io/

    • The decoded JWT token contains the following payload information

    • eg. {

      "aud": "microsoft:identityserver:[clientid]",
      "iss": "http://logon.securexacc.eu/adfs/services/trust",
      "iat": 1649680803,
      "exp": 1649684403,
      "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups": "[Claims]",
      "language": "NL",
      "unique_name": "[unique_name]",
      "given_name": "[firstname user]",
      "family_name": "[lastname user]",
      "email": "[email]",
      "identityCategory": "",
      "apptype": "Public",
      "appid": "[clientid]",
      "authmethod": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
      "auth_time": "2022-04-11T12:40:03.067Z",
      "ver": "1.0",
      "scp": "openid"
      }

  5. The JWT can also be verified using the JWKS at https://logon.securexacc.eu/adfs/discovery/keys. This is an optional step for the client application.

  6. The client application can now initiate a session for the user and can save the accessToken in the browser, or in a session.

  7. The access token can now be used to do subsequent calls

Rate limit

Depending on the product / api we configured a rate limit. When the call rate is exceeded, the caller receives a 429 Too Many Requests response status code.

Webhooks

For the moment we don't support webhooks (yet).